Official Codebase of 3DCodeVerse
Python
harness: refactor batch 1 — shared foundations (TrackInfo/ENTRY_FILE registries, Settings.backends(), GateFinding.as_line, typed AgentJob, RunOptions, codeverse/proc.py; +28 tests, 915 green)
gaoypenga0491faea8a5
diff --git a/harness/bench/out/articulated_v1_flash/battery.json b/harness/bench/out/articulated_v1_flash/battery.jsonnew file mode 100644index 00000000..5d4910f3--- /dev/null+++ b/harness/bench/out/articulated_v1_flash/battery.json@@ -0,0 +1,198 @@+{+ "battery": {+ "name": "articulated_v1",+ "track": "articulated_object",+ "language": "urdf_blender",+ "description": "12 articulated-object prompts (URDF + bpy link meshes), 4 per tier. must_have items name the joints the judge/FK sweep must verify.\n",+ "prompts": [+ {+ "id": "art_easy_cabinet_door",+ "prompt": "a kitchen wall cabinet with a single hinged door that swings open 110 degrees",+ "tier": "easy",+ "category": "furniture",+ "must_have": [+ "cabinet box",+ "one door on a vertical hinge axis",+ "door swings outward up to 110 degrees",+ "handle on the free edge"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_easy_drawer_unit",+ "prompt": "a bedside drawer unit with two drawers that slide out",+ "tier": "easy",+ "category": "furniture",+ "must_have": [+ "carcass",+ "two drawers on prismatic slides",+ "drawers pull out at least 30 cm",+ "drawer pulls"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_easy_laptop",+ "prompt": "a laptop whose screen lid opens from closed to 135 degrees on a hinge at the back edge",+ "tier": "easy",+ "category": "electronics",+ "must_have": [+ "base with keyboard",+ "lid with screen",+ "revolute hinge along the back edge",+ "range 0 to 135 degrees"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_easy_scissors",+ "prompt": "a pair of scissors with two blades pivoting about a central screw",+ "tier": "easy",+ "category": "tools",+ "must_have": [+ "two blade-and-handle halves",+ "one revolute pivot at the screw",+ "blades cross when closed",+ "opens about 60 degrees"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_med_folding_chair",+ "prompt": "a folding chair whose seat lifts up and whose front legs pivot toward the back legs to fold flat",+ "tier": "medium",+ "category": "furniture",+ "must_have": [+ "seat hinged to the frame",+ "front leg frame pivoting about a cross bar",+ "back rest",+ "folds to a flat state"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_med_desk_lamp",+ "prompt": "a desk lamp with a round base, a lower arm that pivots at the base and an upper arm that pivots at the elbow, ending in a shade",+ "tier": "medium",+ "category": "lighting",+ "must_have": [+ "weighted base",+ "lower arm revolute at base",+ "upper arm revolute at elbow",+ "shade at the tip",+ "both joints have limits"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_med_toolbox",+ "prompt": "a metal toolbox with a lid hinged along the back edge and a fold-down carry handle on top of the lid",+ "tier": "medium",+ "category": "tools",+ "must_have": [+ "box body",+ "lid hinged at the rear edge",+ "handle hinged on the lid",+ "lid opens 100 degrees",+ "latch on the front"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_med_wheelbarrow",+ "prompt": "a wheelbarrow with a spinning front wheel and a tray that tips forward on its axle to dump",+ "tier": "medium",+ "category": "garden",+ "must_have": [+ "tray",+ "two handles",+ "two rear legs",+ "front wheel on a continuous axle joint",+ "tipping joint for the tray"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_hard_door_handle",+ "prompt": "a house door in its frame with hinges, a lever handle that rotates down 40 degrees, and a latch bolt that retracts when the handle turns",+ "tier": "hard",+ "category": "architecture",+ "must_have": [+ "door frame",+ "door on vertical hinges",+ "lever handle revolute",+ "latch bolt prismatic",+ "door swings 90 degrees"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_hard_treasure_chest",+ "prompt": "a wooden treasure chest with a domed lid on rear hinges, a hasp that flips over a staple, and a small inner tray that slides sideways",+ "tier": "hard",+ "category": "props",+ "must_have": [+ "chest body",+ "domed lid revolute at rear",+ "hasp revolute on the lid",+ "sliding inner tray",+ "iron bands"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_hard_swivel_chair",+ "prompt": "an office swivel chair with a five-star base on casters, a gas lift that raises the seat, a seat that swivels, and a backrest that tilts back",+ "tier": "hard",+ "category": "furniture",+ "must_have": [+ "five-arm base with five caster wheels",+ "prismatic gas lift",+ "continuous swivel joint",+ "backrest tilt joint with limits",+ "armrests"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "art_hard_bicycle_wheel_stand",+ "prompt": "a bicycle front wheel and fork on a repair stand, with the wheel spinning on its axle, the fork turning about the steering tube, and a brake caliper whose arms pinch the rim",+ "tier": "hard",+ "category": "vehicles",+ "must_have": [+ "spoked wheel on a continuous axle joint",+ "fork on a steering revolute joint",+ "two brake arms pivoting toward the rim",+ "stand base"+ ],+ "dimensions_m": null,+ "tags": []+ }+ ]+ },+ "options": {+ "generator": "api-agent:gemini:gemini-3.7-flash",+ "planner": null,+ "judge": "gemini:gemini-3.1-pro-preview",+ "rounds": 3,+ "max_usd": 2.0,+ "max_minutes": 60.0,+ "parallel": 3,+ "limit": null,+ "ids": [],+ "tiers": [],+ "resume": true+ },+ "started_at": "2026-08-23T11:10:55.448078+00:00"+}\ No newline at end of filediff --git a/harness/bench/out/articulated_v1_flash/results.jsonl b/harness/bench/out/articulated_v1_flash/results.jsonlnew file mode 100644index 00000000..973360f9--- /dev/null+++ b/harness/bench/out/articulated_v1_flash/results.jsonl@@ -0,0 +1,2 @@+{"id":"art_easy_cabinet_door","tier":"easy","category":"furniture","score_baseline":0.964,"score_final":0.964,"passed":true,"rounds":1,"cost_usd":0.3002882,"minutes":4.14,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/articulated_v1_flash/runs/art_easy_cabinet_door","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}+{"id":"art_easy_drawer_unit","tier":"easy","category":"furniture","score_baseline":0.988,"score_final":0.988,"passed":true,"rounds":1,"cost_usd":0.373319525,"minutes":5.29,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/articulated_v1_flash/runs/art_easy_drawer_unit","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}diff --git a/harness/bench/out/static_v1_flash/battery.json b/harness/bench/out/static_v1_flash/battery.jsonnew file mode 100644index 00000000..c5e935c4--- /dev/null+++ b/harness/bench/out/static_v1_flash/battery.json@@ -0,0 +1,383 @@+{+ "battery": {+ "name": "static_objects_v1",+ "track": "static_object",+ "language": "blender",+ "description": "24 static-object prompts, 8 categories \u00d7 3 tiers (easy / medium / hard). Every prompt carries must_have items the planner turns into acceptance checks. Same battery runs under any generator; keep the judge model fixed across arms.\n",+ "prompts": [+ {+ "id": "furn_easy_stool",+ "prompt": "a simple three-legged round wooden stool, 45 cm tall",+ "tier": "easy",+ "category": "furniture",+ "must_have": [+ "round seat",+ "three splayed legs of equal length",+ "legs touch the ground"+ ],+ "dimensions_m": {+ "height": 0.45+ },+ "tags": []+ },+ {+ "id": "furn_med_dining_chair",+ "prompt": "a mid-century wooden dining chair with a slatted backrest and tapered legs",+ "tier": "medium",+ "category": "furniture",+ "must_have": [+ "four tapered legs",+ "seat slab",+ "backrest with at least three vertical slats",+ "back legs continue into back posts"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "furn_hard_rolltop_desk",+ "prompt": "a writing desk with two pedestals of three drawers each, a central knee-hole, a leather inlay top and brass drawer pulls",+ "tier": "hard",+ "category": "furniture",+ "must_have": [+ "two drawer pedestals",+ "three drawers per pedestal with visible fronts",+ "knee-hole gap",+ "brass pull handles",+ "desk top overhangs"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "veh_easy_toy_car",+ "prompt": "a chunky toy car with a rounded body and four thick wheels",+ "tier": "easy",+ "category": "vehicles",+ "must_have": [+ "one-piece rounded body",+ "four wheels touching the ground",+ "wheels protrude sideways"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "veh_med_pickup",+ "prompt": "a pickup truck with a two-door cab, open cargo bed, wheel arches and side mirrors",+ "tier": "medium",+ "category": "vehicles",+ "must_have": [+ "cab with windows",+ "open rear bed",+ "four wheels with hubs",+ "front grille and headlights",+ "side mirrors"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "veh_hard_tractor",+ "prompt": "a farm tractor with large rear tyres with treads, small front wheels, an exposed engine block, exhaust stack, driver seat, steering wheel and a roll bar",+ "tier": "hard",+ "category": "vehicles",+ "must_have": [+ "rear wheels much larger than front wheels",+ "tyre tread detail",+ "exhaust stack",+ "seat and steering wheel",+ "roll bar",+ "engine hood"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "tool_easy_hammer",+ "prompt": "a claw hammer with a wooden handle and a steel head",+ "tier": "easy",+ "category": "tools",+ "must_have": [+ "cylindrical handle",+ "steel head with a flat face",+ "forked claw on the back"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "tool_med_hand_drill",+ "prompt": "a cordless power drill with a pistol grip, trigger, battery pack in the base of the grip and a keyless chuck holding a drill bit",+ "tier": "medium",+ "category": "tools",+ "must_have": [+ "pistol grip body",+ "trigger",+ "battery block under grip",+ "chuck with a bit",+ "side vents"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "tool_hard_bench_vise",+ "prompt": "a cast-iron bench vise with fixed and sliding jaws, a lead screw with a tommy bar handle, guide rails, a small anvil face and mounting base with bolt holes",+ "tier": "hard",+ "category": "tools",+ "must_have": [+ "two jaws with a visible gap",+ "sliding jaw on guide rails",+ "lead screw with sliding T handle",+ "anvil flat",+ "base with bolt holes"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "appl_easy_kettle",+ "prompt": "an electric kettle with a spout, a lid and a side handle on a round base",+ "tier": "easy",+ "category": "appliances",+ "must_have": [+ "pot body",+ "pouring spout",+ "handle opposite the spout",+ "lid on top",+ "round base"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "appl_med_toaster",+ "prompt": "a two-slot retro toaster with rounded chrome body, a lever on the side, a browning dial and a crumb tray",+ "tier": "medium",+ "category": "appliances",+ "must_have": [+ "two bread slots on top",+ "side lever",+ "dial knob",+ "rounded body",+ "small feet"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "appl_hard_espresso",+ "prompt": "an espresso machine with a group head and portafilter, a steam wand, a drip tray with grate, a water tank at the back, and a top-mounted cup warmer with a pressure gauge on the front panel",+ "tier": "hard",+ "category": "appliances",+ "must_have": [+ "portafilter with handle under a group head",+ "steam wand on the side",+ "drip tray with grate",+ "water tank",+ "pressure gauge",+ "cup warmer rail"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "plant_easy_cactus",+ "prompt": "a potted barrel cactus in a terracotta pot with soil",+ "tier": "easy",+ "category": "plants",+ "must_have": [+ "ribbed round cactus body",+ "terracotta pot with rim",+ "soil surface"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "plant_med_palm",+ "prompt": "a small potted palm with a textured trunk and eight arching fronds made of many leaflets",+ "tier": "medium",+ "category": "plants",+ "must_have": [+ "textured trunk",+ "at least eight fronds",+ "fronds arch downward",+ "leaflets along each frond",+ "pot"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "plant_hard_bonsai",+ "prompt": "a bonsai tree with a twisted thick trunk, three layered foliage pads, exposed roots over a rock and a shallow oval ceramic tray with moss",+ "tier": "hard",+ "category": "plants",+ "must_have": [+ "twisted trunk with taper",+ "at least three distinct foliage pads",+ "exposed roots gripping a rock",+ "shallow oval tray",+ "moss surface"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "bld_easy_shed",+ "prompt": "a small garden shed with a pitched roof, one door and one window",+ "tier": "easy",+ "category": "buildings",+ "must_have": [+ "box walls",+ "pitched roof overhang",+ "door on front",+ "window"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "bld_med_lighthouse",+ "prompt": "a tapered lighthouse with red and white bands, a gallery with railing, a glass lantern room and a domed cap, on a rocky base",+ "tier": "medium",+ "category": "buildings",+ "must_have": [+ "tapered tower",+ "alternating bands",+ "gallery walkway with railing",+ "glass lantern room",+ "dome",+ "rock base"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "bld_hard_windmill",+ "prompt": "a Dutch windmill with an octagonal tapered body, thatched cap, four lattice sails, a balcony stage with railing, a door, and two shuttered windows",+ "tier": "hard",+ "category": "buildings",+ "must_have": [+ "octagonal tapered body",+ "cap",+ "four lattice sails in a cross",+ "balcony with railing",+ "door",+ "shuttered windows"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "toy_easy_blocks",+ "prompt": "a stack of five alphabet blocks of decreasing size in a slightly twisted tower",+ "tier": "easy",+ "category": "toys",+ "must_have": [+ "five cubes",+ "decreasing size upward",+ "each slightly rotated",+ "all stacked touching"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "toy_med_rocking_horse",+ "prompt": "a wooden rocking horse with curved rockers, a saddle, handles and a mane",+ "tier": "medium",+ "category": "toys",+ "must_have": [+ "horse body with head and four legs",+ "two curved rockers",+ "saddle",+ "handle grips",+ "mane"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "toy_hard_train",+ "prompt": "a toy steam locomotive with a boiler, smokestack, cab with windows, cowcatcher, six driving wheels with connecting rods, and a coal tender with four wheels",+ "tier": "hard",+ "category": "toys",+ "must_have": [+ "cylindrical boiler",+ "smokestack",+ "cab",+ "cowcatcher",+ "six large wheels with rods",+ "separate tender with coal load and four wheels"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "mus_easy_drum",+ "prompt": "a snare drum with tension rods and two drumsticks resting on top",+ "tier": "easy",+ "category": "musical_instruments",+ "must_have": [+ "cylindrical shell",+ "top head",+ "at least eight tension rods around the rim",+ "two sticks"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "mus_med_acoustic_guitar",+ "prompt": "an acoustic guitar with a figure-eight body, sound hole, bridge, fretted neck, headstock with six tuning pegs and six strings",+ "tier": "medium",+ "category": "musical_instruments",+ "must_have": [+ "figure-eight body",+ "sound hole",+ "bridge",+ "neck with frets",+ "headstock",+ "six tuning pegs",+ "six strings"+ ],+ "dimensions_m": null,+ "tags": []+ },+ {+ "id": "mus_hard_drum_kit",+ "prompt": "a five-piece drum kit with a bass drum with pedal, snare on a stand, two rack toms, a floor tom, a hi-hat and two cymbals on stands, and a throne",+ "tier": "hard",+ "category": "musical_instruments",+ "must_have": [+ "bass drum with pedal",+ "snare on stand",+ "two mounted toms",+ "floor tom with legs",+ "hi-hat with two cymbals",+ "two crash/ride cymbals on stands",+ "drum throne"+ ],+ "dimensions_m": null,+ "tags": []+ }+ ]+ },+ "options": {+ "generator": "api-agent:gemini:gemini-3.7-flash",+ "planner": null,+ "judge": "gemini:gemini-3.1-pro-preview",+ "rounds": 3,+ "max_usd": 2.0,+ "max_minutes": 60.0,+ "parallel": 4,+ "limit": null,+ "ids": [],+ "tiers": [],+ "resume": true+ },+ "started_at": "2026-08-23T11:10:43.831385+00:00"+}\ No newline at end of filediff --git a/harness/bench/out/static_v1_flash/results.jsonl b/harness/bench/out/static_v1_flash/results.jsonlnew file mode 100644index 00000000..c6180b1c--- /dev/null+++ b/harness/bench/out/static_v1_flash/results.jsonl@@ -0,0 +1,5 @@+{"id":"furn_med_dining_chair","tier":"medium","category":"furniture","score_baseline":null,"score_final":null,"passed":null,"rounds":0,"cost_usd":0.0,"minutes":0.92,"status":"error","errors":"ModelError: Gemini API error 503: This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.\nl=self.plan_model)\n ^^^^^^^^^^^^^^^^^^^^^^\n File \"/home/yipeng/3dcodeverse/harness/codeverse/orchestrator/runner.py\", line 91, in stage\n result = fn()\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/lifecycle.py\", line 147, in <lambda>\n ctx.plan = runner.stage(\"plan\", lambda: self._plan_stage(ctx), inputs={\"spec\": plan_stage_inputs(spec), \"track\": self.track.value},\n ~~~~~~~~~~~~~~~~^^^^^\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/lifecycle.py\", line 230, in _plan_stage\n plan = run_planner(ctx.spec, ctx.spec.backends.planner, self.plan_model, ctx.ws, model=self._planner_model,\n events=ctx.events, budget=ctx.budget, runtime=ctx.runtime)\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/planner.py\", line 48, in plan\n result, usage = plan_with_usage(spec, model_id, plan_model, ws, model=model, events=events, runtime=runtime)\n ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/planner.py\", line 70, in plan_with_usage\n resp = model.generate(req)\n File \"/home/yipeng/3dcodeverse/harness/codeverse/models/gemini.py\", line 257, in generate\n raise err from exc\ncodeverse.models.base.ModelError: Gemini API error 503: This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.\n","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/furn_med_dining_chair","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}+{"id":"furn_easy_stool","tier":"easy","category":"furniture","score_baseline":0.75,"score_final":0.75,"passed":true,"rounds":1,"cost_usd":0.30198767499999996,"minutes":4.46,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/furn_easy_stool","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}+{"id":"veh_easy_toy_car","tier":"easy","category":"vehicles","score_baseline":0.282,"score_final":0.85,"passed":true,"rounds":3,"cost_usd":1.6814668499999998,"minutes":20.78,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/veh_easy_toy_car","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}+{"id":"furn_hard_rolltop_desk","tier":"hard","category":"furniture","score_baseline":0.7,"score_final":0.75,"passed":true,"rounds":3,"cost_usd":1.2165176,"minutes":22.52,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/furn_hard_rolltop_desk","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}+{"id":"tool_easy_hammer","tier":"easy","category":"tools","score_baseline":0.944,"score_final":0.944,"passed":true,"rounds":1,"cost_usd":0.40064702500000005,"minutes":5.59,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/tool_easy_hammer","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}diff --git a/harness/codeverse/config.py b/harness/codeverse/config.pyindex 57baa80c..3f23f969 100644--- a/harness/codeverse/config.py+++ b/harness/codeverse/config.py@@ -20,6 +20,8 @@ import yamlfrom pydantic import BaseModel, Fieldfrom pydantic_settings import BaseSettings, SettingsConfigDict+from codeverse.contracts.common import Backends+_LEGACY_KEYS_FILE = Path.home() / ".config" / "astra3d" / "gemini_keys.env"_USER_CONFIG = Path.home() / ".config" / "codeverse" / "config.yaml"@@ -67,14 +69,33 @@ class Settings(BaseSettings):openai_api_key: str = ""openai_base_url: str = ""- default_planner: str = "gemini:gemini-3.7-flash"- default_generator: str = "api-agent:gemini:gemini-3.7-flash"- # The judge drives the refine loop: the pro tier has ~3x lower sample noise than flash- # (calibration 2026-08-23: std 0.03 vs 0.08-0.12) for ~$0.07 per verdict.- default_judge: str = "gemini:gemini-3.1-pro-preview"+ # Backend-role defaults: the literals live in ONE place — contracts/common.py::Backends+ # (which also documents why the judge default is the pro tier).+ default_planner: str = Field(default_factory=lambda: Backends().planner)+ default_generator: str = Field(default_factory=lambda: Backends().generator)+ default_judge: str = Field(default_factory=lambda: Backends().judge)+ default_captioner: str = Field(default_factory=lambda: Backends().captioner)default_candidates: int = Field(default=1, description="best-of-N baseline candidates (tracks read it)")# ------------------------------------------------------------------ helpers+ def backends(self, **overrides: str | None) -> Backends:+ """The ``Backends`` for a new Spec from the settings defaults. Keyword+ overrides (``planner`` / ``generator`` / ``judge`` / ``captioner``) win+ when truthy; ``None`` / ``""`` falls through to the default."""+ base: dict[str, str] = {+ "planner": self.default_planner,+ "generator": self.default_generator,+ "judge": self.default_judge,+ "captioner": self.default_captioner,+ }+ unknown = set(overrides) - set(base)+ if unknown:+ raise TypeError(f"unknown backend role(s): {sorted(unknown)} (roles: {sorted(base)})")+ for role, value in overrides.items():+ if value:+ base[role] = value+ return Backends(**base)+def resolve_blender(self) -> str:if self.binaries.blender and Path(self.binaries.blender).exists():return self.binaries.blenderdiff --git a/harness/codeverse/contracts/__init__.py b/harness/codeverse/contracts/__init__.pyindex 01cb2c65..376dda8f 100644--- a/harness/codeverse/contracts/__init__.py+++ b/harness/codeverse/contracts/__init__.py@@ -11,7 +11,7 @@ Modules:- ``agent`` CodingAgent job/result shapes."""-from codeverse.contracts.agent import AgentJob, AgentResult, FileChange+from codeverse.contracts.agent import AgentJob, AgentResult, ApiAgentOptions, FileChangefrom codeverse.contracts.artifacts import (BuildResult,GateFinding,@@ -32,7 +32,20 @@ from codeverse.contracts.chat import (ToolResultPart,ToolSpec,)-from codeverse.contracts.common import Backends, Budget, Language, Track, Usage, Vec3+from codeverse.contracts.common import (+ ENTRY_FILE,+ LANGUAGE_LABEL,+ TRACK_INFO,+ TRACK_LANGUAGES,+ Backends,+ Budget,+ Language,+ Track,+ TrackInfo,+ Usage,+ Vec3,+ code_file,+)from codeverse.contracts.judgment import ImprovementItem, JudgeIssue, Judgmentfrom codeverse.contracts.plan import (AcceptanceItem,@@ -51,6 +64,6 @@ from codeverse.contracts.plan import (ZonePlan,)from codeverse.contracts.run import RoundRecord, RunRecord, RunStatus-from codeverse.contracts.spec import Constraints, ReferenceImage, Spec+from codeverse.contracts.spec import Constraints, ReferenceImage, RunOptions, Spec__all__ = [name for name in dir() if not name.startswith("_")]diff --git a/harness/codeverse/contracts/agent.py b/harness/codeverse/contracts/agent.pyindex 82a3ecd2..19ed0bb3 100644--- a/harness/codeverse/contracts/agent.py+++ b/harness/codeverse/contracts/agent.py@@ -4,7 +4,7 @@ from __future__ import annotationsfrom typing import Any-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, model_validatorfrom codeverse.contracts.common import Usage@@ -16,6 +16,20 @@ class FileChange(BaseModel):lines_removed: int = 0+class ApiAgentOptions(BaseModel):+ """Knobs honoured only by the in-process ``api-agent`` backend."""++ max_usd: float = Field(default=0.0, description="stop the session when its own cost exceeds this (0 = no cap)")+ temperature: float = 0.3+ thinking: str = "low"+ allow_shell: bool = True+++#: legacy ``AgentJob.extra`` keys lifted into the typed fields (values stay in extra too)+_LEGACY_JOB_KEYS = ("round", "kind", "language", "track", "files_hint", "mcp_command")+_LEGACY_API_KEYS = ("max_usd", "temperature", "thinking", "allow_shell")++class AgentJob(BaseModel):workspace: strprompt: str@@ -28,7 +42,40 @@ class AgentJob(BaseModel):spatial_tools: bool = Field(default=True, description="expose the 3dcv MCP spatial tools to the agent")write_roots: list[str] = Field(default_factory=lambda: ["src", "public"], description="dirs the agent may edit")env: dict[str, str] = Field(default_factory=dict)- extra: dict[str, Any] = Field(default_factory=dict)+ # ------------------------------------------------------------- typed job context+ round: int = Field(default=0, description="round index → trajectory dir + ToolContext")+ kind: str = Field(default="", description="task kind: baseline | refine | repair | asset | zone ...")+ language: str = Field(default="", description="spec language (spatial tool filtering)")+ track: str = Field(default="", description="spec track (spatial tool filtering)")+ files_hint: list[str] = Field(+ default_factory=list,+ description="workspace-relative files/dirs this task is expected to touch — attributes "+ "files_changed between concurrent sessions in one workspace",+ )+ mcp_command: list[str] | None = Field(default=None, description="override for the 3dcv MCP server command")+ api: ApiAgentOptions = Field(default_factory=ApiAgentOptions)+ extra: dict[str, Any] = Field(default_factory=dict, description="one-off backend hints (legacy keys are lifted)")++ @model_validator(mode="before")+ @classmethod+ def _lift_legacy_extra(cls, data: Any) -> Any:+ """Constructors that pass ``extra={"round": 2, ...}`` keep working: known keys+ are lifted into the typed fields. ``extra`` itself is left untouched so+ existing ``job.extra[...]`` readers see exactly what they were given."""+ if not isinstance(data, dict):+ return data+ extra = data.get("extra")+ if not isinstance(extra, dict):+ return data+ data = dict(data) # never mutate the caller's dict+ for key in _LEGACY_JOB_KEYS:+ if key in extra and key not in data:+ data[key] = extra[key]+ if "api" not in data:+ lifted = {k: extra[k] for k in _LEGACY_API_KEYS if k in extra}+ if lifted:+ data["api"] = lifted+ return dataclass AgentResult(BaseModel):diff --git a/harness/codeverse/contracts/artifacts.py b/harness/codeverse/contracts/artifacts.pyindex 10e06325..5fa6b5b9 100644--- a/harness/codeverse/contracts/artifacts.py+++ b/harness/codeverse/contracts/artifacts.py@@ -24,6 +24,31 @@ class GateFinding(BaseModel):fix_hint: str = Field(default="", description="concrete, copyable instruction for the fixer")data: dict[str, Any] = Field(default_factory=dict)+ def as_line(+ self,+ *,+ with_gate: bool = False,+ with_severity: bool = False,+ with_target: bool = False,+ with_hint: bool = True,+ ) -> str:+ """One presentation line for prompts/reports — no leading ``- `` (callers+ own their list bullets). ``message`` is always present; the flags opt in+ to a ``GATE <gate>:`` prefix, a ``[<severity>]`` tag, a `` [<target>]``+ suffix and the `` FIX: <fix_hint>`` suffix (default on, when non-empty)."""+ parts: list[str] = []+ if with_gate:+ parts.append(f"GATE {self.gate}:")+ if with_severity:+ parts.append(f"[{self.severity.value}]")+ parts.append(self.message)+ line = " ".join(parts)+ if with_target and self.target:+ line += f" [{self.target}]"+ if with_hint and self.fix_hint:+ line += f" FIX: {self.fix_hint}"+ return line+class GateReport(BaseModel):gate: str@@ -91,6 +116,10 @@ class RenderView(BaseModel):look_at: Vec3 | None = Nonefov: float | None = Nonetime_s: float | None = Field(default=None, description="animation time for scenes")+ judge: bool | None = Field(+ default=None,+ description="True/False once the judge subset is stamped at render time; None = not stamped (legacy rounds)",+ )class RenderSet(BaseModel):@@ -101,3 +130,4 @@ class RenderSet(BaseModel):duration_ms: int = 0console_errors: list[str] = Field(default_factory=list, description="(scenes) JS/WebGL errors seen")fps: float | None = None+ out_dir: str = Field(default="", description="directory the views (+ views.json/metrics.json) were written to")diff --git a/harness/codeverse/contracts/common.py b/harness/codeverse/contracts/common.pyindex e1a280c2..86258f22 100644--- a/harness/codeverse/contracts/common.py+++ b/harness/codeverse/contracts/common.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom enum import StrEnumfrom typing import Annotated-from pydantic import BaseModel, Field+from pydantic import BaseModel, ConfigDict, FieldVec3 = Annotated[tuple[float, float, float], Field(description="x, y, z")]@@ -40,6 +40,58 @@ TRACK_LANGUAGES: dict[Track, tuple[Language, ...]] = {}+class TrackInfo(BaseModel):+ """Per-track registry row: default judge rubric + human label.++ THE single source for what used to be restated as ``TRACK_RUBRIC`` /+ ``RUBRIC_BY_TRACK`` / ``TYPE_LABEL`` in judges, texturing, flywheel and cli.+ """++ model_config = ConfigDict(frozen=True)++ rubric: str = Field(description="rubric name under judges/rubrics/, e.g. 'static_object_v1'")+ label: str = Field(description="human label for galleries / captions / reports")+++#: one registry row per track+TRACK_INFO: dict[Track, TrackInfo] = {+ Track.STATIC_OBJECT: TrackInfo(rubric="static_object_v1", label="3D Objects"),+ Track.ARTICULATED_OBJECT: TrackInfo(rubric="articulated_v1", label="Articulated Objects"),+ Track.SCENE: TrackInfo(rubric="scene_v1", label="3D Scenes"),+ Track.GRAPHICS: TrackInfo(rubric="shader_v1", label="Procedural Graphics"),+}++#: entry file inside the workspace per language — the file a build starts from.+#: THE single source for entry paths (runtimes' first entry_glob, flywheel export).+ENTRY_FILE: dict[Language, str] = {+ Language.BLENDER: "src/model.py",+ Language.CADQUERY: "src/model.py",+ Language.URDF_BLENDER: "src/model.py",+ Language.THREEJS: "src/object.js",+ Language.SCENE_THREEJS: "src/scene.js",+ Language.GLSL_SHADER: "src/shader.frag",+ Language.OPENGL_PYTHON: "src/program.py",+}++#: human label per language (galleries, captions, reports)+LANGUAGE_LABEL: dict[Language, str] = {+ Language.BLENDER: "Blender Python",+ Language.CADQUERY: "CadQuery (Python)",+ Language.URDF_BLENDER: "URDF + Blender Python",+ Language.THREEJS: "Three.js (ESM)",+ Language.SCENE_THREEJS: "Three.js scene (multi-file ESM + GLSL)",+ Language.GLSL_SHADER: "GLSL fragment shader",+ Language.OPENGL_PYTHON: "OpenGL (moderngl Python + GLSL)",+}+++def code_file(language: Language) -> str:+ """Top-level flywheel copy of the entry file: ``code`` + the entry suffix+ (``code.py`` / ``code.js`` / ``code.frag``)."""+ entry = ENTRY_FILE[language]+ return "code" + entry[entry.rfind(".") :]++class Usage(BaseModel):"""Normalised token/cost accounting for ONE model or agent call."""@@ -88,5 +140,7 @@ class Backends(BaseModel):planner: str = "gemini:gemini-3.7-flash"generator: str = "api-agent:gemini:gemini-3.7-flash"+ # The judge drives the refine loop: the pro tier has ~3x lower sample noise than+ # flash (calibration 2026-08-23: std 0.03 vs 0.08-0.12) for ~$0.07 per verdict.judge: str = "gemini:gemini-3.1-pro-preview"captioner: str = "gemini:gemini-3.7-flash"diff --git a/harness/codeverse/contracts/spec.py b/harness/codeverse/contracts/spec.pyindex dac2a5f8..7665922e 100644--- a/harness/codeverse/contracts/spec.py+++ b/harness/codeverse/contracts/spec.py@@ -28,6 +28,17 @@ class Constraints(BaseModel):must_not: list[str] = Field(default_factory=list)+class RunOptions(BaseModel):+ """Run-shape options frozen on the spec (distinct from Budget and Backends).++ ``None`` / ``False`` means "not stated": resolution falls through to+ ``run_state.extra`` (legacy runs) and then ``Settings`` defaults.+ """++ candidates: int | None = Field(default=None, ge=1, description="best-of-N baseline candidates")+ texture: bool = Field(default=False, description="run the derived texture pass after the loop")++class Spec(BaseModel):id: strtrack: Track@@ -37,6 +48,7 @@ class Spec(BaseModel):constraints: Constraints = Field(default_factory=Constraints)budget: Budget = Field(default_factory=Budget)backends: Backends = Field(default_factory=Backends)+ options: RunOptions = Field(default_factory=RunOptions)seed: int = 0tags: list[str] = Field(default_factory=list)created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))diff --git a/harness/codeverse/conventions.py b/harness/codeverse/conventions.pyindex 7db79d08..f1258c3c 100644--- a/harness/codeverse/conventions.py+++ b/harness/codeverse/conventions.py@@ -9,6 +9,8 @@ Frames* ``blender`` / ``cadquery`` / ``urdf``: **Z-up, -Y is the object's front**,meters. (Blender's "Front" view looks along +Y, so a front face points -Y.)* ``threejs`` / ``scene_threejs``: **Y-up, +Z is the front**, meters.+* ``glsl_shader`` / ``opengl_python``: **Y-up, +Z front** (GL clip space is+ Y-up; harness cameras/gates treat graphics output like the three.js frame).* Canonical exchange format is **GLB (glTF 2.0): Y-up, +Z front, meters**.Blender's glTF exporter maps (x, y, z) → (x, z, -y), so a Blender -Y frontbecomes glTF +Z front — the two native frames agree once exported.@@ -45,6 +47,9 @@ LANGUAGE_FRAME: dict[str, Frame] = {"urdf_blender": Frame.Z_UP_NEG_Y_FRONT,"threejs": Frame.Y_UP_POS_Z_FRONT,"scene_threejs": Frame.Y_UP_POS_Z_FRONT,+ # GL clip space is Y-up: graphics output is framed like the three.js/glTF frame.+ "glsl_shader": Frame.Y_UP_POS_Z_FRONT,+ "opengl_python": Frame.Y_UP_POS_Z_FRONT,}GLB_FRAME = Frame.Y_UP_POS_Z_FRONTdiff --git a/harness/codeverse/proc.py b/harness/codeverse/proc.pynew file mode 100644index 00000000..0110e391--- /dev/null+++ b/harness/codeverse/proc.py@@ -0,0 +1,99 @@+"""Subprocess + atomic-JSON primitives shared across the harness.++One home for the run-a-child-process pattern (own process group, wall-clock+timeout, group kill, captured output) and the tmp+rename JSON write. Peer of+``workspace.py``; stdlib-only — imports nothing from ``codeverse`` so wrappers,+spatial helpers and agents can all use it without layering back-edges.++``languages/_common.py`` currently carries the same helpers for its runtime+callers; it will become a re-export of this module.+"""++from __future__ import annotations++import json+import os+import signal+import subprocess+import time+from collections.abc import Callable, Mapping+from dataclasses import dataclass+from pathlib import Path+from typing import Any+++@dataclass(frozen=True)+class ProcResult:+ """Outcome of one subprocess run."""++ returncode: int+ stdout: str+ stderr: str+ timed_out: bool+ duration_ms: int+++def run_subprocess(+ cmd: list[str],+ *,+ cwd: Path | str,+ timeout_s: float,+ env: Mapping[str, str] | None = None,+ stdin_text: str | None = None,+ preexec_fn: Callable[[], None] | None = None,+) -> ProcResult:+ """Run ``cmd`` in its own process group; kill the whole group on timeout.++ Never raises on non-zero exit — callers inspect :attr:`ProcResult.returncode`.+ ``preexec_fn`` runs in the child before exec (e.g. rlimits); the child is+ always started in a new session so :func:`kill_group` reaps grandchildren.+ """+ t0 = time.monotonic()+ proc = subprocess.Popen(+ cmd,+ cwd=str(cwd),+ env=dict(env) if env is not None else None,+ stdin=subprocess.PIPE if stdin_text is not None else subprocess.DEVNULL,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ text=True,+ start_new_session=True,+ preexec_fn=preexec_fn,+ )+ timed_out = False+ try:+ out, err = proc.communicate(input=stdin_text, timeout=timeout_s)+ except subprocess.TimeoutExpired:+ timed_out = True+ kill_group(proc)+ out, err = proc.communicate()+ return ProcResult(+ returncode=proc.returncode if proc.returncode is not None else -1,+ stdout=out or "",+ stderr=err or "",+ timed_out=timed_out,+ duration_ms=int((time.monotonic() - t0) * 1000),+ )+++def kill_group(proc: subprocess.Popen[str]) -> None:+ """SIGKILL ``proc``'s whole process group (fall back to just the child)."""+ try:+ os.killpg(proc.pid, signal.SIGKILL)+ except (ProcessLookupError, PermissionError):+ proc.kill()+++def tail(text: str, *, max_lines: int = 40, max_chars: int = 4000) -> str:+ """Last ``max_lines`` lines of ``text``, capped at ``max_chars`` characters."""+ lines = text.splitlines()[-max_lines:]+ s = "\n".join(lines)+ return s[-max_chars:] if len(s) > max_chars else s+++def write_json_atomic(path: Path, data: Any) -> None:+ """tmp + rename so readers never see a partial file."""+ path.parent.mkdir(parents=True, exist_ok=True)+ tmp = path.with_suffix(path.suffix + ".tmp")+ tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False, default=str))+ tmp.replace(path)diff --git a/harness/codeverse/workspace.py b/harness/codeverse/workspace.pyindex 576312a5..e35a6e79 100644--- a/harness/codeverse/workspace.py+++ b/harness/codeverse/workspace.py@@ -19,6 +19,7 @@ from typing import Anyfrom pydantic import BaseModelfrom codeverse.contracts.agent import FileChange+from codeverse.proc import write_json_atomic_DIRS = ("src", "public", "artifacts", "artifacts/renders", "artifacts/gates", "artifacts/judge", "trajectories")@@ -92,12 +93,9 @@ class Workspace:# ----------------------------------------------------------------- json iodef write_json(self, path: Path, model: BaseModel | dict[str, Any]) -> None:- """Atomic JSON write (tmp + rename)."""- path.parent.mkdir(parents=True, exist_ok=True)- tmp = path.with_suffix(path.suffix + ".tmp")+ """Atomic JSON write (tmp + rename, via :func:`codeverse.proc.write_json_atomic`)."""data = model.model_dump(mode="json") if isinstance(model, BaseModel) else model- tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False))- tmp.replace(path)+ write_json_atomic(path, data)def read_json(self, path: Path) -> dict[str, Any]:return json.loads(path.read_text())diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex dea8e564..1738f9b7 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -68,11 +68,16 @@ the flywheel unit.codeverse/conventions.py frames (LANGUAGE_FRAME, GLB_FRAME), units, OBJECT_VIEWS/_QUICK, SCENE_VIEWS,to_snake/to_pascal/slugify, MAX_TRIS_*, BBOX_TOLERANCE_M, CONTACT_GAP_M (THE source)- config.py Settings (CV3D_* env, ~/.config/codeverse/config.yaml; default_judge=gemini-3.1-pro-preview,+ config.py Settings (CV3D_* env, ~/.config/codeverse/config.yaml; role defaults come from+ contracts Backends; Settings.backends(**overrides) builds a Spec's Backends;default_candidates=1)- contracts/ pydantic: common (Track, Language, Usage, Budget, Backends), spec, plan, artifacts,- judgment, run, chat, agent+ contracts/ pydantic: common (Track, Language, Usage, Budget, Backends, TRACK_INFO registry,+ ENTRY_FILE/code_file/LANGUAGE_LABEL tables), spec (+ RunOptions), plan, artifacts+ (GateFinding.as_line, RenderView.judge, RenderSet.out_dir), judgment, run, chat,+ agent (typed AgentJob + ApiAgentOptions)workspace.py run-dir layout + git snapshots ; events.py JSONL event log+ proc.py stdlib-only subprocess + atomic-JSON primitives (run_subprocess w/ group kill ++ preexec_fn, kill_group, tail, write_json_atomic) — shared by languages/spatial/climodels/ ChatModel; gemini.py (dead-key + free 429 rotation), gemini_image.py (ImageModel),anthropic.py openai.py, keypool.py ('dead' outcome), pricing.py (version-suffix-onlyfallback), retry.py, schema_utils.py (strict schema: no null-for-default), registry.py@@ -283,10 +288,7 @@ $0.02–0.03 (flash) / ~$0.2 (pro); api-agent generation 3–6 min per object ro`n_samples ≥ 3` for decisions. Detail crops are position-heuristic (no 2D partboxes yet).* `scene_frames` gate + judge-view subset are built (renders side) but not yet- wired into the scene track; `conventions.LANGUAGE_FRAME` lacks- glsl_shader/opengl_python entries (stopgap `setdefault` in `tracks/graphics.py`);- `3dcv judge` lacks a GRAPHICS → shader_v1 mapping; `flywheel export` lacks- graphics entry-file mappings.+ wired into the scene track.* Articulated: candidate selection uses the quick 4-view sheet (not pose views);mimic joints ignored; sweep is O(links² × poses).* Scenes: fps is a relative cost; camera-in-geometry can miss open-back enclosures.diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 88c7ff8e..a17ca2ea 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -20,6 +20,27 @@ file was reconciled against it on 2026-08-23 (waves 2–3 + fix batch 1).`gemini-3.1-flash-image`, fallback `gemini-2.5-flash-image`) behind the`ImageModel` protocol (`generate`, `generate_with_usage` → `(images, Usage)`).+## core (contracts · config · proc)++```python+from codeverse.contracts import TRACK_INFO, TrackInfo # {Track: TrackInfo(rubric, label)} — THE track registry+from codeverse.contracts import ENTRY_FILE, code_file, LANGUAGE_LABEL # {Language: "src/<entry>"}; code_file(lang) -> "code.<ext>"+from codeverse.contracts import RunOptions # Spec.options: candidates (int|None, ≥1), texture (bool)+GateFinding.as_line(with_gate=False, with_severity=False, with_target=False, with_hint=True) -> str+ # "GATE <gate>: [<sev>] <message> [<target>] FIX: <hint>" — flags opt in; no leading "- "+RenderView.judge: bool | None # stamped True/False at render time; None = legacy round (fall back to select_judge_views)+RenderSet.out_dir: str # directory the views (+ views.json/metrics.json) were written to ("" on old rounds)+from codeverse.config import get_settings+get_settings().backends(planner=..., generator=..., judge=..., captioner=...) -> Backends+ # settings defaults (default_planner/... mirror contracts Backends literals; + default_captioner);+ # truthy keyword overrides win, None/"" falls through, unknown role -> TypeError+from codeverse.proc import ProcResult, run_subprocess, kill_group, tail, write_json_atomic+run_subprocess(cmd, *, cwd, timeout_s, env=None, stdin_text=None, preexec_fn=None) -> ProcResult+ # own session/process group, group-kill on timeout, never raises on rc != 0; stdlib-only module+```+`Spec.options` is plan-hash safe (`plan_stage_inputs` whitelists spec fields).+`Workspace.write_json` delegates to `proc.write_json_atomic`.+## models/```pythonfrom codeverse.models import get_chat_model # (model_id) -> ChatModel, lru-cached, thread-safe@@ -73,11 +94,14 @@ res = agent.run(AgentJob(workspace=..., prompt=..., label="baseline", timeout_s=res.ok, res.exit_reason # completed | timeout | error | budget | model_substitutedres.files_changed (git-derived, attributed per session), res.usage, res.transcript_path, res.tool_calls, res.errors```-`AgentJob.extra` keys honoured by every agent: `round`, `kind`, `language`, `track`,-`mcp_command` (override), `max_usd` / `temperature` / `thinking` / `allow_shell`-(api-agent only), **Δ `files_hint`** (list of workspace-relative files/dirs the task-is expected to touch — used to attribute `files_changed` between concurrent sessions-in one workspace; harness-owned paths and sibling sessions' hinted files are dropped).+`AgentJob` carries typed job context: `round`, `kind`, `language`, `track`,+`mcp_command` (override), `files_hint` (workspace-relative files/dirs the task is+expected to touch — used to attribute `files_changed` between concurrent sessions in+one workspace; harness-owned paths and sibling sessions' hinted files are dropped)+and `job.api: ApiAgentOptions(max_usd, temperature, thinking, allow_shell)` (api-agent+only). **Δ legacy lift**: the same keys passed inside `extra={...}` are lifted into+the typed fields at validation (extra itself is left untouched), so old constructors+and serialized jobs keep working; `extra` stays for one-off backend hints.Trajectories: `ws/trajectories/<label>_rNN/{prompt.md, transcript.jsonl, stdout.json,stderr.log, result.json}`; **Δ** a re-run of the same label+round lands in`<label>.a2_rNN` (then `.a3` …) — the first attempt is never overwritten; `result.json`diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex dcfd244e..c5f5c343 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -160,13 +160,14 @@ Protocol and judge calibration: `docs/EVAL.md`.## 8. Extending (plugin paths)-* **New language**: enum in `contracts/common.py::Language` (+ `TRACK_LANGUAGES`),- frame in `conventions.LANGUAGE_FRAME`; `languages/<lang>/{runtime.py, lint.py,- skeleton.py, CONTRACT.md, wrappers/}` implementing `LanguageRuntime`; branch in- `languages/base.py::get_runtime`; `prompts/<lang>/contract.md` + `cookbook.md`- (every snippet must run — `tests/prompts` executes them); entry-file mappings in- `flywheel/sample.py`; part→file mapping via `runtime.file_for_part` (blender and- threejs have it; `tracks/prompting.file_for_target_factory` picks it up).+* **New language**: enum in `contracts/common.py::Language` (+ `TRACK_LANGUAGES`,+ `ENTRY_FILE`, `LANGUAGE_LABEL`), frame in `conventions.LANGUAGE_FRAME`;+ `languages/<lang>/{runtime.py, lint.py, skeleton.py, CONTRACT.md, wrappers/}`+ implementing `LanguageRuntime`; branch in `languages/base.py::get_runtime`;+ `prompts/<lang>/contract.md` + `cookbook.md` (every snippet must run —+ `tests/prompts` executes them); part→file mapping via `runtime.file_for_part`+ (blender and threejs have it; `tracks/prompting.file_for_target_factory` picks+ it up).* **New spatial tool**: pydantic args + `@tool("name", Args, "…", tracks=(…),languages=(…), cost_hint=…)` in `spatial/tools*.py` (imported from`spatial/tools.py`); available to tracks, MCP, api-agent and prompt cards at once.diff --git a/harness/tests/core/test_config_backends.py b/harness/tests/core/test_config_backends.pynew file mode 100644index 00000000..ce51c726--- /dev/null+++ b/harness/tests/core/test_config_backends.py@@ -0,0 +1,43 @@+"""Settings.backends() — one source of backend-role defaults (Batch-1)."""++from __future__ import annotations++import pytest++from codeverse.config import Settings+from codeverse.contracts.common import Backends+++def test_settings_defaults_mirror_backends():+ s = Settings()+ assert s.backends() == Backends()+ assert s.default_planner == Backends().planner+ assert s.default_generator == Backends().generator+ assert s.default_judge == Backends().judge+ assert s.default_captioner == Backends().captioner+++def test_settings_overrides_flow_through():+ s = Settings(default_generator="single-shot:gemini:gemini-3.7-flash", default_captioner="gemini:x")+ b = s.backends()+ assert b.generator == "single-shot:gemini:gemini-3.7-flash"+ assert b.captioner == "gemini:x"+ assert b.planner == Backends().planner+++def test_backends_keyword_overrides_win_when_truthy():+ s = Settings()+ b = s.backends(judge="gemini:custom", planner=None, generator="")+ assert b.judge == "gemini:custom"+ assert b.planner == Backends().planner # None falls through+ assert b.generator == Backends().generator # "" falls through+++def test_backends_rejects_unknown_role():+ with pytest.raises(TypeError, match="unknown backend role"):+ Settings().backends(judger="x")+++def test_env_override_still_wins(monkeypatch):+ monkeypatch.setenv("CV3D_DEFAULT_CAPTIONER", "gemini:from-env")+ assert Settings().backends().captioner == "gemini:from-env"diff --git a/harness/tests/core/test_contract_additions.py b/harness/tests/core/test_contract_additions.pynew file mode 100644index 00000000..8ee930f3--- /dev/null+++ b/harness/tests/core/test_contract_additions.py@@ -0,0 +1,160 @@+"""Batch-1 contract additions: registries, as_line, typed AgentJob, RunOptions."""++from __future__ import annotations++import pytest+from pydantic import ValidationError++from codeverse.contracts import (+ ENTRY_FILE,+ LANGUAGE_LABEL,+ TRACK_INFO,+ TRACK_LANGUAGES,+ AgentJob,+ ApiAgentOptions,+ Language,+ RunOptions,+ Spec,+ Track,+ code_file,+)+from codeverse.contracts.artifacts import GateFinding, RenderSet, RenderView, Severity+++# ------------------------------------------------------------------ registries+def test_track_info_covers_every_track_and_is_frozen():+ assert set(TRACK_INFO) == set(Track)+ assert TRACK_INFO[Track.STATIC_OBJECT].rubric == "static_object_v1"+ assert TRACK_INFO[Track.ARTICULATED_OBJECT].rubric == "articulated_v1"+ assert TRACK_INFO[Track.SCENE].rubric == "scene_v1"+ assert TRACK_INFO[Track.GRAPHICS].rubric == "shader_v1"+ with pytest.raises(ValidationError):+ TRACK_INFO[Track.SCENE].rubric = "other" # frozen+++def test_entry_file_and_labels_cover_every_language():+ assert set(ENTRY_FILE) == set(Language)+ assert set(LANGUAGE_LABEL) == set(Language)+ assert all(e.startswith("src/") for e in ENTRY_FILE.values())+ assert code_file(Language.BLENDER) == "code.py"+ assert code_file(Language.THREEJS) == "code.js"+ assert code_file(Language.GLSL_SHADER) == "code.frag"+++def test_registries_agree_with_legacy_flywheel_tables():+ """Drift guard while the legacy tables still exist (they adopt these later)."""+ import codeverse.flywheel.sample as sample++ legacy_entry = getattr(sample, "ENTRY_BY_LANGUAGE", None)+ if legacy_entry is not None:+ assert legacy_entry == ENTRY_FILE+ legacy_code = getattr(sample, "CODE_FILE_BY_LANGUAGE", None)+ if legacy_code is not None:+ assert legacy_code == {lang: code_file(lang) for lang in Language}+ legacy_label = getattr(sample, "TYPE_LABEL", None)+ if legacy_label is not None:+ assert legacy_label == {t: TRACK_INFO[t].label for t in Track}+++def test_language_frame_covers_every_language():+ from codeverse.conventions import LANGUAGE_FRAME, Frame++ assert set(LANGUAGE_FRAME) == {lang.value for lang in Language}+ assert LANGUAGE_FRAME["glsl_shader"] is Frame.Y_UP_POS_Z_FRONT+ assert LANGUAGE_FRAME["opengl_python"] is Frame.Y_UP_POS_Z_FRONT+++# ------------------------------------------------------------------ as_line+def _finding(**kw) -> GateFinding:+ base = dict(gate="contract", severity=Severity.ERROR, target="leg_1", message="leg floats", fix_hint="drop z by 0.02")+ base.update(kw)+ return GateFinding(**base)+++def test_as_line_default_is_message_plus_fix():+ assert _finding().as_line() == "leg floats FIX: drop z by 0.02"+ assert _finding(fix_hint="").as_line() == "leg floats"+++def test_as_line_flag_combinations():+ f = _finding()+ assert f.as_line(with_gate=True, with_hint=False) == "GATE contract: leg floats"+ assert f.as_line(with_severity=True, with_hint=False) == "[error] leg floats"+ assert f.as_line(with_target=True, with_hint=False) == "leg floats [leg_1]"+ assert (f.as_line(with_gate=True, with_severity=True, with_target=True)+ == "GATE contract: [error] leg floats [leg_1] FIX: drop z by 0.02")+ assert not f.as_line().startswith("- ")+++def test_as_line_skips_empty_target():+ assert _finding(target=None).as_line(with_target=True, with_hint=False) == "leg floats"+++# ------------------------------------------------------------------ render flags+def test_render_view_judge_flag_defaults_none():+ v = RenderView(name="front", path="front.png")+ assert v.judge is None+ assert RenderView(name="front", path="front.png", judge=True).judge is True+ assert RenderSet().out_dir == ""+++# ------------------------------------------------------------------ AgentJob+def test_agent_job_legacy_extra_is_lifted_and_kept():+ extra = {"round": 2, "kind": "refine", "language": "blender", "track": "static_object",+ "files_hint": ["src/a.py"], "mcp_command": ["python", "-m", "x"],+ "max_usd": 1.5, "temperature": 0.7, "thinking": "high", "allow_shell": False}+ j = AgentJob(workspace="w", prompt="p", extra=dict(extra))+ assert (j.round, j.kind, j.language, j.track) == (2, "refine", "blender", "static_object")+ assert j.files_hint == ["src/a.py"]+ assert j.mcp_command == ["python", "-m", "x"]+ assert j.api == ApiAgentOptions(max_usd=1.5, temperature=0.7, thinking="high", allow_shell=False)+ assert j.extra == extra # untouched: legacy readers see what they were given+++def test_agent_job_explicit_fields_beat_extra():+ j = AgentJob(workspace="w", prompt="p", round=5, api=ApiAgentOptions(max_usd=9.0),+ extra={"round": 2, "max_usd": 1.0})+ assert j.round == 5+ assert j.api.max_usd == 9.0+++def test_agent_job_defaults_and_roundtrip():+ j = AgentJob(workspace="w", prompt="p")+ assert j.round == 0 and j.kind == "" and j.files_hint == [] and j.mcp_command is None+ assert j.api == ApiAgentOptions()+ j2 = AgentJob(workspace="w", prompt="p", extra={"round": 3, "temperature": 0.9})+ assert AgentJob(**j2.model_dump()) == j2 # dump/construct stable+++# ------------------------------------------------------------------ RunOptions+def test_spec_options_default_and_legacy_json():+ s = Spec(id="x", track=Track.STATIC_OBJECT, language=Language.BLENDER, prompt="a chair")+ assert s.options == RunOptions()+ d = s.model_dump(mode="json")+ d.pop("options")+ s2 = Spec(**d) # old spec.json without options still parses+ assert s2.options.candidates is None and s2.options.texture is False+++def test_spec_options_roundtrip_and_validation():+ s = Spec(id="x", track=Track.SCENE, language=Language.SCENE_THREEJS, prompt="p",+ options=RunOptions(candidates=3, texture=True))+ s2 = Spec(**s.model_dump(mode="json"))+ assert s2.options == RunOptions(candidates=3, texture=True)+ with pytest.raises(ValidationError):+ RunOptions(candidates=0) # ge=1+++def test_spec_options_do_not_change_the_plan_stage_hash():+ from codeverse.orchestrator.runner 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")+ opted = plain.model_copy(update={"options": RunOptions(candidates=4, texture=True)})+ assert hash_inputs(plan_stage_inputs(plain)) == hash_inputs(plan_stage_inputs(opted))+++def test_track_languages_still_the_gate():+ assert set(TRACK_LANGUAGES) == set(Track)+ with pytest.raises(ValidationError):+ Spec(id="x", track=Track.SCENE, language=Language.BLENDER, prompt="p")diff --git a/harness/tests/core/test_proc.py b/harness/tests/core/test_proc.pynew file mode 100644index 00000000..84da0596--- /dev/null+++ b/harness/tests/core/test_proc.py@@ -0,0 +1,89 @@+"""codeverse/proc.py — subprocess primitives (Batch-1 foundations)."""++from __future__ import annotations++import json+import os+import resource+import time+from pathlib import Path++from codeverse.proc import ProcResult, kill_group, run_subprocess, tail, write_json_atomic+++def test_run_subprocess_captures_output(tmp_path: Path):+ r = run_subprocess(["bash", "-c", "echo out; echo err >&2; exit 3"], cwd=tmp_path, timeout_s=10)+ assert isinstance(r, ProcResult)+ assert r.returncode == 3+ assert r.stdout.strip() == "out"+ assert r.stderr.strip() == "err"+ assert not r.timed_out+ assert r.duration_ms >= 0+++def test_run_subprocess_stdin(tmp_path: Path):+ r = run_subprocess(["cat"], cwd=tmp_path, timeout_s=10, stdin_text="hello")+ assert r.stdout == "hello"+++def test_timeout_kills_the_whole_process_group(tmp_path: Path):+ """A timed-out child AND its grandchildren die (killpg on the new session)."""+ r = run_subprocess(["bash", "-c", "sleep 30 & echo $!; wait"], cwd=tmp_path, timeout_s=0.4)+ assert r.timed_out+ assert r.returncode != 0+ grandchild = int(r.stdout.strip().splitlines()[0])+ deadline = time.monotonic() + 3.0+ while time.monotonic() < deadline:+ try:+ os.kill(grandchild, 0)+ except ProcessLookupError:+ return # gone — group kill worked+ time.sleep(0.05)+ raise AssertionError(f"grandchild sleep (pid {grandchild}) survived the group kill")+++def test_preexec_fn_runs_in_the_child(tmp_path: Path):+ soft = 256++ def limit() -> None:+ resource.setrlimit(resource.RLIMIT_NOFILE, (soft, soft))++ r = run_subprocess(+ ["python3", "-c", "import resource, sys; sys.stdout.write(str(resource.getrlimit(resource.RLIMIT_NOFILE)[0]))"],+ cwd=tmp_path, timeout_s=20, preexec_fn=limit,+ )+ assert r.stdout.strip() == str(soft)+++def test_kill_group_is_public_and_tolerates_dead_proc(tmp_path: Path):+ import subprocess++ proc = subprocess.Popen(["sleep", "0.05"], start_new_session=True)+ proc.wait()+ kill_group(proc) # must not raise on an already-reaped child+++def test_tail_caps_lines_and_chars():+ text = "\n".join(f"line{i}" for i in range(100))+ t = tail(text, max_lines=5)+ assert t.splitlines() == [f"line{i}" for i in range(95, 100)]+ assert len(tail("x" * 10000, max_chars=100)) == 100+++def test_write_json_atomic_no_partial_file(tmp_path: Path):+ p = tmp_path / "deep" / "out.json"+ write_json_atomic(p, {"a": 1, "p": Path("b")})+ assert json.loads(p.read_text()) == {"a": 1, "p": "b"}+ assert not p.with_suffix(".json.tmp").exists()+++def test_workspace_write_json_delegates(tmp_ws):+ from pydantic import BaseModel++ class M(BaseModel):+ x: int = 2++ p = tmp_ws.root / "artifacts" / "m.json"+ tmp_ws.write_json(p, M())+ assert json.loads(p.read_text()) == {"x": 2}+ assert not p.with_suffix(".json.tmp").exists()