Official Codebase of 3DCodeVerse
Python
config: one switch grammar — every C3D_* switch is a Settings field; env_flag, skills/config.py and the hand parsers are gone
gaoypenga415484cd02c
diff --git a/eval/bench/ab_plan.py b/eval/bench/ab_plan.pyindex 8b6f2212..9f4f327f 100644--- a/eval/bench/ab_plan.py+++ b/eval/bench/ab_plan.py@@ -19,9 +19,8 @@ shell never reaches the control either. With these mechanics the OFF arm is themeans turning skills OFF helped).Why each arm is a child PROCESS rather than a thread: the switches under test are read-from the environment (``codeverse3d.tracks.planner.brief_enabled`` reads ``os.environ`` at-call time; anything under ``Settings`` is read once through an ``lru_cache``), so two-threads in one interpreter cannot hold different values of them. A child gets exactly+from the environment (each is a ``Settings`` field, read once per process through an+``lru_cache``), so two threads in one interpreter cannot hold different values of them. A child gets exactlythe env its arm needs and nothing leaks across. The driver pins both children at``C3D_MAX_IN_FLIGHT`` (default 16); the in-flight slots are machine-wide lock files, sothe two arms share those 16 with each other and with every other harness process@@ -130,7 +129,7 @@ log = logging.getLogger(__name__)DEFAULT_GENERATOR = Backends().generatorDEFAULT_JUDGE = "gemini:gemini-3.1-pro-preview"#: the per-child cap. The flat name is a first-class alias of ``C3D_RATE__MAX_IN_FLIGHT``-#: since 2026-08-24 (``Settings._FLAT_ALIASES``; before that it was read by nothing) and+#: since 2026-08-24 (``Settings.FLAT``; before that it was read by nothing) and#: wins over the nested spelling when both are set.MAX_IN_FLIGHT_ENV = "C3D_MAX_IN_FLIGHT"#: the nested spelling: popped from every child's env so it cannot fight the flat one@@ -707,13 +706,13 @@ def main(argv: Sequence[str] | None = None) -> int:# A KEY no code path reads makes the variant arm byte-identical to the control, so# the battery costs a full run and yields a verdict about nothing. One such A/B is# on record printing "keep, mean delta +0.344" (CQ-5).- from codeverse3d.tracks.plan_features import DEAD_SWITCHES, dead_env_keys+ from codeverse3d.tracks.plan_features import dead_env_keysdead = dead_env_keys(opts.variant_env)if dead and len(dead) == len(opts.variant_env):_parser().error("--variant-env only sets switches nothing reads, so both arms would be identical: "- + "; ".join(f"{k} ({DEAD_SWITCHES[k]})" for k in dead)+ + ", ".join(dead) + " (no Settings field reads them)"+ " (pass --aa if an identical-arms calibration run is the point)")if opts.pin_plan and (blockers := pin_plan_blockers(opts.variant_env)):diff --git a/eval/docs/PAPER_WRITING.md b/eval/docs/PAPER_WRITING.mdindex 5578fa62..5da7ef06 100644--- a/eval/docs/PAPER_WRITING.md+++ b/eval/docs/PAPER_WRITING.md@@ -562,9 +562,10 @@ data the repo does not carry; they are marked in the caveat column.## 9.3 The switches this work added, and their state-Every one is read at call time and registered in `tracks/plan_features.LIVE_SWITCHES`, which-a test enforces by grepping the tree; a switch nothing reads once produced "keep, mean delta-+0.344" on two byte-identical arms, which is why the registry exists.+Every one is a `Settings` field, and `tracks/plan_features` derives from those fields which+names are live (since 2026-09-22; before, a hand-kept registry and a test grepping the tree); a+switch nothing reads once produced "keep, mean delta +0.344" on two byte-identical arms, which+is why ab_plan refuses one.| switch | what it does | default | why ||---|---|---|---|diff --git a/eval/tests/test_ab_plan_switches.py b/eval/tests/test_ab_plan_switches.pyindex 1f0b5925..da859b46 100644--- a/eval/tests/test_ab_plan_switches.py+++ b/eval/tests/test_ab_plan_switches.py@@ -62,17 +62,19 @@ def test_a_skills_ab_spells_its_off_arm_explicitly(monkeypatch):identical arms, the byte-identical-arms trap tracks/plan_features.py exists for."""from bench._ab_report import CONTROL, VARIANTfrom bench.ab_plan import AbOptions, child_env- from codeverse3d.skills.config import SKILLS_ENV, skills_enabled+ from codeverse3d.config import Settings++ skills = "C3D_SKILLS"def enabled(env: dict[str, str]) -> bool:- monkeypatch.delenv(SKILLS_ENV, raising=False)- if SKILLS_ENV in env:- monkeypatch.setenv(SKILLS_ENV, env[SKILLS_ENV])- return skills_enabled()+ monkeypatch.delenv(skills, raising=False)+ if skills in env:+ monkeypatch.setenv(skills, env[skills])+ return Settings().skills- shell = {"PATH": "/usr/bin", SKILLS_ENV: "0"} # exported in the launching shell: never reaches the control- off = AbOptions(variant_env={SKILLS_ENV: "0"})+ shell = {"PATH": "/usr/bin", skills: "0"} # exported in the launching shell: never reaches the control+ off = AbOptions(variant_env={skills: "0"})assert enabled(child_env(CONTROL, off, shell)) is Trueassert enabled(child_env(VARIANT, off, shell)) is False- on = AbOptions(variant_env={SKILLS_ENV: "1"})+ on = AbOptions(variant_env={skills: "1"})assert enabled(child_env(CONTROL, on, shell)) is enabled(child_env(VARIANT, on, shell)) is Truediff --git a/harness/codeverse3d/config.py b/harness/codeverse3d/config.pyindex 502e46db..0e8c6c58 100644--- a/harness/codeverse3d/config.py+++ b/harness/codeverse3d/config.py@@ -7,6 +7,11 @@ written to run records. The names before D78 (``~/.config/codeverse/config.yamlGemini keys: ``GEMINI_API_KEYS`` (csv) or ``GEMINI_API_KEY`` or the owner's``~/.config/astra3d/gemini_keys.env`` file (read-only compatibility).++One switch grammar: every ``C3D_*`` knob the harness reads is a field here, read through+``get_settings()`` at the call that uses it — no module reads the environment by hand. A+field ``x`` is ``C3D_X`` (a nested ``section.x`` is ``C3D_SECTION__X``, plus the flat+spellings in :data:`Settings.FLAT`); an on/off switch is a :data:`Flag`."""from __future__ import annotations@@ -17,10 +22,20 @@ import reimport shutilfrom functools import lru_cachefrom pathlib import Path-from typing import Any, ClassVar, Literal+from typing import Annotated, Any, ClassVar, Literalimport yaml-from pydantic import BaseModel, Field, model_validator+from pydantic import (+ BaseModel,+ BeforeValidator,+ Field,+ ValidationError,+ ValidationInfo,+ ValidatorFunctionWrapHandler,+ WrapValidator,+ model_validator,+)+from pydantic_core import PydanticUseDefaultfrom pydantic_settings import BaseSettings, SettingsConfigDictfrom codeverse3d.contracts.common import Backends@@ -31,14 +46,24 @@ _USER_CONFIG = Path.home() / ".config" / "3dcodeverse" / "config.yaml"_LEGACY_USER_CONFIG = Path.home() / ".config" / "codeverse" / "config.yaml"-def _lower_bound(model: type[BaseModel], field: str) -> int | None:- """The ``ge=`` declared on ``model.field`` (None when unbounded). Lets a flat env- alias enforce exactly the bound its target field declares, in one place."""- for meta in model.model_fields[field].metadata:- lo = getattr(meta, "ge", None)- if lo is not None:- return int(lo)- return None+log = logging.getLogger(__name__)+++def _or_default(value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any:+ """A switch that does not parse warns and keeps its DEFAULT (D44 c): a typo in a bench+ command runs the arm that never set it — not a crash mid-battery, and not the variant."""+ try:+ return handler(value.strip() if isinstance(value, str) else value)+ except ValidationError:+ log.warning("C3D_%s=%r does not parse; using the default", (info.field_name or "?").upper(), value)+ raise PydanticUseDefault() from None+++#: an on/off switch: on/off, 1/0, true/false, yes/no (any case, t/f and y/n too); anything+#: else warns and keeps the field's default+Flag = Annotated[bool, WrapValidator(_or_default)]+#: a switch that is a count (>= 0); anything else warns and keeps the field's default+Count = Annotated[int, Field(ge=0), WrapValidator(_or_default)]class Binaries(BaseModel):@@ -65,7 +90,9 @@ class Render(BaseModel):height: int = 768scene_width: int = 1024scene_height: int = 576- gpu: str = Field(default="auto", description="auto | on | off (headless Chrome WebGL backend)")+ gpu: Annotated[Literal["auto", "on", "off"], BeforeValidator(lambda v: str(v).strip().lower())] = Field(+ default="auto", description="headless Chrome WebGL backend (C3D_RENDER__GPU, or the flat C3D_RENDER_GPU "+ "the node side reads too)")sheet_cols: int = 4sheet_tile: int = 384@@ -84,14 +111,14 @@ class Limits(BaseModel):# render pass, whose tail is minutes long.max_parallel_agents: int = Field(default=12, ge=1, description="thread fan-out for agent tasks (>= 1)")max_parallel_builds: int = Field(default=8, ge=1, description="concurrent build subprocesses (>= 1)")- agent_max_turns: int = Field(+ agent_max_turns: Count = Field(default=0,- ge=0,description="hard cap on model turns per agent session (0 = the backend's own default, ""which is what ships: a 28-turn cap cost $0.02 more and 0.205 of a score point in its "- "own A/B — docs/COST.md §17 — so no profile sets one; name it here if you want one).",+ "own A/B — docs/COST.md §17 — so no profile sets one; name it here or as "+ "C3D_AGENT_MAX_TURNS if you want one).",)- seed_recipes: bool = Field(+ seed_recipes: Flag = Field(default=True,description="graphics / glsl_shader: paste the cookbook recipes the brief calls for ""(curtain / aurora / stars / bokehSoft / dropsLayer + the hash / noise / fbm helpers "@@ -101,7 +128,7 @@ class Limits(BaseModel):"the prompt carried the verified curtain() recipe five times and the agent used it zero ""times — round 0 was again a comb of bars (comb_artefact, 0.33); and (eval/bench/out/seed_v1) ""recipes seeded into the agent's own common.glsl were overwritten before the end of the run. "- "`C3D_SEED_RECIPES=0` (read at call time by `seed_recipes_enabled`) is the control arm.",+ "`C3D_SEED_RECIPES=0` is the control arm.",)@@ -153,108 +180,39 @@ class Judge(BaseModel):"Slice render is local CPU; no profile touches this dial (the channel measured ≤ $0).")-#: The recipe-seeding switch (Limits.seed_recipes). Read at CALL time by-#: :func:`seed_recipes_enabled`, never only through the cached Settings: ``eval/bench/ab_plan.py``-#: differs its arms by environment alone, and a value frozen at first ``get_settings()``-#: would hand the variant the control's behaviour (the CQ-5 lesson, tracks/plan_features.py).-SEED_RECIPES_ENV = "C3D_SEED_RECIPES"-#: wire the scene texture pack into the scene loop (a stage before env/zones, and the-#: pack description in both prompts). OFF by default: it adds an image-model call per-#: run, and whether it earns that is a measurement nobody has made yet.-SCENE_TEXTURES_ENV = "C3D_SCENE_TEXTURES"-_TRUE_WORDS = frozenset({"1", "on", "true", "yes", "y"})-_FALSE_WORDS = frozenset({"0", "off", "false", "no", "n"})---def _env_flag(raw: str, env: str) -> bool:- word = raw.strip().lower()- if word in _TRUE_WORDS:- return True- if word in _FALSE_WORDS:- return False- raise ValueError(f"{env}={raw!r}: expected on/off (1/0, true/false, yes/no)")---def env_flag(env: str, fallback: bool) -> bool:- """``$env`` read NOW (never through the cached Settings — an A/B arm sets it after- first touch): unset or empty → ``fallback``; garbage → OFF with a warning, because a- typo in a bench command must produce a control run, not a crash mid-battery (and- not the variant: ``fallback`` may be on). ``skills/config.py`` reads its switches- through this too."""- raw = os.environ.get(env)- if raw is not None and raw.strip():- try:- return _env_flag(raw, env)- except ValueError as e:- logging.getLogger(__name__).warning("%s; treating it as off", e)- return False- return fallback---def scene_textures_enabled() -> bool:- """Is the scene texture stage on for THIS call? ``$C3D_SCENE_TEXTURES``, else off.-- The pack generator (``texturing.plan.scene_texture_pack``) and the prompt snippet that- describes it (``texture_pack_prompt`` — whose docstring already says "for zone/env- generation") have existed since the texturing work, but nothing in ``tracks/scene.py``- called either: the switch `Spec.options.texture` does nothing on this track and the- generator was never told a pack could exist. Measured on eval/bench/out/scene_baseline- (2026-09-05): four of the five scored cells' judge complaints are the GROUND being a- flat untextured colour, in near-identical words, and that is the most consistent- defect in the battery.- """- return env_flag(SCENE_TEXTURES_ENV, False)---def seed_recipes_enabled() -> bool:- """Is recipe seeding (``tracks/graphics.py:seed_recipes``) on for THIS call? ``$C3D_SEED_RECIPES``- when it is set, else ``Settings.limits.seed_recipes`` (default ON)."""- return env_flag(SEED_RECIPES_ENV, get_settings().limits.seed_recipes)--class Settings(BaseSettings):- model_config = SettingsConfigDict(env_prefix="C3D_", env_nested_delimiter="__", extra="ignore")-- #: Flat aliases for nested knobs people actually type. ``C3D_MAX_IN_FLIGHT=16`` was- #: written into three launch commands and two workflow briefs on 2026-08-24 before anyone- #: noticed pydantic-settings only reads ``C3D_RATE__MAX_IN_FLIGHT`` — every one of them- #: silently ran at the default 64. An env knob that is read by nothing is worse than no- #: knob; both spellings now work and the doctor prints the short one.- _FLAT_ALIASES: ClassVar[dict[str, tuple[str, str]]] = {+ # env_ignore_empty: ``C3D_X=`` is unset, never "" (an empty C3D_CACHE_DIR was the cwd)+ model_config = SettingsConfigDict(env_prefix="C3D_", env_nested_delimiter="__", extra="ignore",+ env_ignore_empty=True)++ #: Nested knobs that also have a flat spelling — the name the docs, the node side and the+ #: A/B commands type. ``C3D_MAX_IN_FLIGHT=16`` went into three launch commands on+ #: 2026-08-24 before anyone noticed only ``C3D_RATE__MAX_IN_FLIGHT`` was read. The flat+ #: one wins when both are set; the nested field validates it.+ FLAT: ClassVar[dict[str, tuple[str, str]]] = {"C3D_MAX_IN_FLIGHT": ("rate", "max_in_flight"),- # the spelling every doc and gpu_launch.cjs use; only C3D_RENDER__GPU was read"C3D_RENDER_GPU": ("render", "gpu"),- SEED_RECIPES_ENV: ("limits", "seed_recipes"),+ "C3D_SEED_RECIPES": ("limits", "seed_recipes"),+ "C3D_AGENT_MAX_TURNS": ("limits", "agent_max_turns"),}- @model_validator(mode="after")- def _apply_flat_aliases(self) -> Settings:- for env, (section, field) in self._FLAT_ALIASES.items():- raw = os.environ.get(env)- if raw is None or raw.strip() == "":- continue- sub = getattr(self, section)- value: int | bool | str- ann = type(sub).model_fields[field].annotation- if ann is bool:- value = _env_flag(raw, env)- elif ann is str: # render.gpu is the only str alias: validate its enum here- value = raw.strip().lower()- if value not in ("auto", "on", "off"):- raise ValueError(f"{env}={raw!r}: expected auto|on|off")- else:- try:- value = int(raw)- except ValueError as e:- raise ValueError(f"{env}={raw!r}: expected an integer") from e- # plain assignment does NOT re-validate (no validate_assignment), so the target- # field's own bound is enforced here — and the message names the variable the- # operator actually typed, not the nested field they never heard of.- lo = _lower_bound(type(sub), field)- if lo is not None and value < lo:- raise ValueError(f"{env}={raw!r}: must be >= {lo}")- setattr(sub, field, value)- return self+ @classmethod+ def settings_customise_sources(cls, settings_cls: Any, init_settings: Any, env_settings: Any,+ dotenv_settings: Any, file_secret_settings: Any) -> tuple[Any, ...]:+ """``C3D_*`` beats the yaml files (``get_settings`` passes those as init kwargs, which+ pydantic-settings ranks FIRST): a switch in a config file must never override the+ environment an A/B arm runs under."""+ return env_settings, init_settings, dotenv_settings, file_secret_settings++ @model_validator(mode="before")+ @classmethod+ def _flat_spellings(cls, data: Any) -> Any:+ for env, (section, name) in cls.FLAT.items():+ raw = os.environ.get(env, "").strip()+ if raw and isinstance(data, dict):+ sub = data.get(section) or {}+ data[section] = {**(sub.model_dump() if isinstance(sub, BaseModel) else sub), name: raw}+ return dataruns_dir: Path = Field(default=Path("runs"))cache_dir: Path = Field(default=Path.home() / ".cache" / "codeverse3d")@@ -292,6 +250,48 @@ class Settings(BaseSettings):cost_ledger: bool = Field(default=True, description="append one priced row per model call ""to the run's telemetry/cost.jsonl (or a per-process log)")+ # ------------------------------------------------------------------ switches+ # The A/B switches and runtime overrides, each read as C3D_<NAME> at the call that uses+ # it. An A/B arm is a child process with its own environment (eval/bench/ab_plan.py), and+ # tracks/plan_features.py derives which C3D_* names are live from these fields.+ skills: Flag = Field(default=True, description="route, materialise and measure skill bundles "+ "(D81, on since 2026-09-22); C3D_SKILLS=0 is an A/B's no-skills arm")+ skills_max: Count = Field(+ default=5, description="bundles attached to one session (skills design §5.2 law 1)")+ skills_unverified: Flag = Field(default=True, description="also route the bundles labelled "+ "inherited-unverified (with it all 17 route; the cap still holds)")+ skills_only: str = Field(default="", description="comma list: the router considers ONLY these "+ "bundles, so an effect A/B can attribute its delta to one; an unknown name "+ "routes nothing, which shows up at once as a variant equal to its control")+ skills_dir: Path | None = Field(default=None, description="another skill library (tests, the live "+ "CLI smoke, a private overlay)")+ plan_brief: Flag = Field(default=True, description="expand the engineering brief before planning "+ "(object tracks)")+ plan_restart: Flag = Field(default=True, description="re-sample a degenerate plan from the original "+ "prompt instead of editing it in context (docs/COST.md §30)")+ scoped_parts: Flag = Field(default=True, description="per-part scoped baseline sessions for an object "+ "of 8+ parts")+ reference_diff: Flag = Field(default=True, description="the judge's reference-image mismatch pass")+ zone_layouts: Flag = Field(default=True, description="scene track: the L2 zone-layout planner calls")+ scene_textures: Flag = Field(default=False, description="scene track: generate a texture pack before "+ "env/zones and describe it in both prompts. OFF: an image-model call per "+ "run, unmeasured — though 4 of 5 scored cells of scene_baseline "+ "(2026-09-05) complained about a flat, untextured ground")+ axis_repair: Flag = Field(default=True, description="articulated track: rewrite a joint axis the "+ "measured motion proves wrong, before the sweep renders")+ settle: Flag = Field(default=True, description="scene driver: the boot-time auto-seat")+ camera_repair: Flag = Field(default=True, description="scene driver: move a camera out of geometry "+ "(zero triggers on a healthy battery; the case it exists for is fatal)")+ auto_exposure: Flag = Field(default=False, description="scene driver: bounded scene-wide exposure "+ "into the healthy band")+ post: Flag = Field(default=True, description="scene pictures: the GTAO + bloom + grade post chain")+ stream: Flag = Field(default=True, description="Gemini: stream replies with inter-chunk stall "+ "detection (a hung buffered read held the socket for the whole attempt)")+ ipv4: Flag = Field(default=True, description="Gemini: bind the transport to IPv4 (the WSL2 IPv6 "+ "path dropped responses silently)")+ runtime_js: Path | None = Field(default=None, description="the node runtime directory; a "+ "non-editable install must point this at a checkout")+# ------------------------------------------------------------------ helpersdef backends(self, **overrides: str | None) -> Backends:"""The ``Backends`` for a new Spec from the settings defaults. Keyword@@ -373,8 +373,7 @@ class Settings(BaseSettings):``C3D_RUNTIME_JS`` overrides the location (the wheel does not packageruntime_js, so a non-editable install MUST point this at a checkout).Missing dir → a loud error at first use instead of a cryptic node crash."""- override = os.environ.get("C3D_RUNTIME_JS", "").strip()- d = Path(override).expanduser() if override else Path(__file__).resolve().parent.parent / "runtime_js"+ d = self.runtime_js.expanduser() if self.runtime_js else Path(__file__).resolve().parent.parent / "runtime_js"if not d.is_dir():raise RuntimeError(f"runtime_js not found at {d} — install the harness editable (pip install -e harness) "diff --git a/harness/codeverse3d/doctor.py b/harness/codeverse3d/doctor.pyindex 5b7ca6d8..1b418b5c 100644--- a/harness/codeverse3d/doctor.py+++ b/harness/codeverse3d/doctor.py@@ -231,12 +231,12 @@ def check_skills() -> list[Row]:the wiring gets a check you can run before spending money."""from codeverse3d.agents.backends import ALLOWED_TOOLS, SYSTEM_SETTINGSfrom codeverse3d.skills import bundle_dirs, skills_dir, validate_bundle- from codeverse3d.skills.config import skills_enabledfrom codeverse3d.skills.materialize import SKILL_ROOTSfrom codeverse3d.skills.registry import ROUTED_SKILLS- rows: list[Row] = [("skills switch", "OK" if skills_enabled() else "WARN",- "C3D_SKILLS on (the default since 2026-09-22)" if skills_enabled()+ on = get_settings().skills+ rows: list[Row] = [("skills switch", "OK" if on else "WARN",+ "C3D_SKILLS on (the default since 2026-09-22)" if onelse "C3D_SKILLS=0: no skill is attached to any session")]dirs = bundle_dirs()if not dirs:diff --git a/harness/codeverse3d/judges/vlm_judge.py b/harness/codeverse3d/judges/vlm_judge.pyindex 7e687f0c..3f672a9b 100644--- a/harness/codeverse3d/judges/vlm_judge.py+++ b/harness/codeverse3d/judges/vlm_judge.py@@ -27,7 +27,7 @@ from dataclasses import dataclass, fieldfrom pathlib import Pathfrom typing import Any, Literal-from codeverse3d.config import env_flag, get_settings+from codeverse3d.config import get_settingsfrom codeverse3d.contracts.artifacts import Judgment, RenderViewfrom codeverse3d.contracts.chat import ChatRequest, ChatResponsefrom codeverse3d.contracts.common import Usage@@ -347,7 +347,6 @@ NEUTRAL_SCORE = 0.5#: ``*_34`` names are the pre-D47 rig, kept for re-judging stored runs.DIFF_VIEW_NAMES: tuple[str, ...] = ("front", "front_right_high", "front_left_high", "right", "left","front_right_34", "front_left_34")-_ENV_DIFF = "C3D_REFERENCE_DIFF"def iou_to_score(iou: float) -> float:@@ -355,8 +354,8 @@ def iou_to_score(iou: float) -> float:def _diff_enabled(flag: bool) -> bool:- """``$C3D_REFERENCE_DIFF`` at call time; a typo reads as OFF (``config.env_flag``)."""- return flag and env_flag(_ENV_DIFF, True)+ """``flag`` unless ``C3D_REFERENCE_DIFF`` switched the pass off (``Settings.reference_diff``)."""+ return flag and get_settings().reference_diffdef _is_synth(note: str) -> bool:diff --git a/harness/codeverse3d/models/gemini.py b/harness/codeverse3d/models/gemini.pyindex b6226d58..d37dd2ea 100644--- a/harness/codeverse3d/models/gemini.py+++ b/harness/codeverse3d/models/gemini.py@@ -14,7 +14,6 @@ from __future__ import annotationsimport ioimport logging-import osimport reimport threadingimport time@@ -195,7 +194,7 @@ _RETRY_DELAY_RE = re.compile(r"retryDelay['\"]?\s*:\s*['\"]?(\d+(?:\.\d+)?)s")#: rest of the retry budget intact, while a legitimate 930 s plan streams tokens#: continuously (145 tok/s p50, audit 2026-08-27) and is bounded only by its#: attempt budget. Generous vs the longest silent prefix we allow for thinking-#: before the first chunk. ``C3D_STREAM=0`` restores the buffered call.+#: before the first chunk. ``C3D_STREAM=off`` restores the buffered call.STREAM_STALL_S = 300.0_pools: dict[tuple[str, ...], KeyPool] = {}@@ -294,15 +293,11 @@ def _ipv4_client_args() -> dict[str, Any]:"""Bind the sync transport to IPv4. Every one of tonight's five hung reads saton an IPv6 destination (2001:4860::/32) with the response headers never arriving— the WSL2 IPv6 path drops these silently and a buffered read then holds the- socket for the whole attempt budget. ``C3D_IPV4=0`` restores the default+ socket for the whole attempt budget. ``C3D_IPV4=off`` restores the default(dual-stack) resolution."""- if os.environ.get("C3D_IPV4", "1") == "0":- return {}- return {"transport": httpx.HTTPTransport(local_address="0.0.0.0")}-+ from codeverse3d.config import get_settings-def _streaming_enabled() -> bool:- return os.environ.get("C3D_STREAM", "1") != "0"+ return {"transport": httpx.HTTPTransport(local_address="0.0.0.0")} if get_settings().ipv4 else {}def _drain_stream(@@ -506,7 +501,9 @@ class GeminiModel:warnings: list[str],) -> ChatResponse:client = _client_for(key, self.timeout_s, self._client_factory)- if not _streaming_enabled():+ from codeverse3d.config import get_settings++ if not get_settings().stream: # C3D_STREAM=off: the buffered callwith Stopwatch() as sw:resp = client.models.generate_content(model=self.model, contents=contents, config=configdiff --git a/harness/codeverse3d/skills/__init__.py b/harness/codeverse3d/skills/__init__.pyindex fbe933c1..862e75e2 100644--- a/harness/codeverse3d/skills/__init__.py+++ b/harness/codeverse3d/skills/__init__.py@@ -28,7 +28,6 @@ is behind ``C3D_SKILLS``: ON by default since 2026-09-22, ``C3D_SKILLS=0`` turnsfrom __future__ import annotationsimport logging-import osfrom collections.abc import Iteratorfrom pathlib import Path@@ -43,15 +42,14 @@ from codeverse3d.skills.model import (log = logging.getLogger(__name__)-#: point the library somewhere else (tests, the live CLI smoke, a private overlay)-SKILLS_DIR_ENV = "C3D_SKILLS_DIR"--def skills_dir() -> Path:- """The bundle root, resolved at call time so an installed wheel works too."""- override = os.environ.get(SKILLS_DIR_ENV, "").strip()+ """The bundle root (``C3D_SKILLS_DIR`` points it elsewhere), resolved at call time so an+ installed wheel works too."""+ from codeverse3d.config import get_settings++ override = get_settings().skills_dirif override:- return Path(override).expanduser()+ return override.expanduser()try:from importlib.resources import files@@ -105,12 +103,10 @@ def load_skill(name: str, root: Path | None = None) -> Skill:return parse_skill(d)-from codeverse3d.skills.config import skills_enabled, skills_max, skills_unverified # noqa: E402from codeverse3d.skills.materialize import attach_skills, materialize_skills # noqa: E402from codeverse3d.skills.registry import plan_signals, select, skills_for # noqa: E402from codeverse3d.skills.telemetry import probe_reads # noqa: E402-__all__ = ["SKILLS_DIR_ENV", "Skill", "SkillError", "SkillRef", "all_skills", "attach_skills", "bundle_dirs",+__all__ = ["Skill", "SkillError", "SkillRef", "all_skills", "attach_skills", "bundle_dirs","iter_skills", "load_skill", "materialize_skills", "plan_signals", "probe_reads", "select",- "skills_dir", "skills_enabled", "skills_for", "skills_max", "skills_unverified",- "validate_bundle"]+ "skills_dir", "skills_for", "validate_bundle"]diff --git a/harness/codeverse3d/skills/config.py b/harness/codeverse3d/skills/config.pydeleted file mode 100644index 22ad2b44..00000000--- a/harness/codeverse3d/skills/config.py+++ /dev/null@@ -1,94 +0,0 @@-"""The three switches that gate the whole skill system — read from the environment NOW.--WHY not ``Settings``: ``codeverse3d.config.get_settings`` is ``lru_cache``d, so a value-read through it is frozen at first touch and an A/B arm that sets the variable after-import gets the control's behaviour. ``eval/bench/ab_plan.py`` differs its arms only by-environment, and a wave once printed "keep, mean delta +0.344" for two byte-identical-arms because the switch it flipped was read by nothing at all-(``codeverse3d/tracks/plan_features.py``). So: one module, read at call time, registered-in ``plan_features.LIVE_SWITCHES``, and a test that greps the tree to prove it is read.--* ``C3D_SKILLS`` — ON by default (2026-09-22). On = route, materialise, measure;- ``C3D_SKILLS=0`` turns the whole system off (an A/B's no-skills arm must say so explicitly:- ``ab_plan.py --variant-env C3D_SKILLS=0``).-* ``C3D_SKILLS_MAX`` — attached bundles per session (default 5, design §5.2 law 1).-* ``C3D_SKILLS_UNVERIFIED`` — also route bundles labelled ``inherited-unverified`` (the- cadquery / threejs forms and the four scene-graphics ports). ON by default with the- switch above, so all 17 bundles route; ``C3D_SKILLS_UNVERIFIED=0`` drops those six.-* ``C3D_SKILLS_ONLY`` — comma list; the router may consider ONLY these bundles.--WHY both defaults flipped ON (owner, 2026-09-22). They shipped OFF on 2026-08-25/26-because the in-process ``api-agent`` read 0 of 5 routed bundles and the A/B could not-resolve an effect (docs/SKILLS.md §6). That backend was deleted 2026-08-28; every-backend left is a vendor CLI with its own native skill loader, and the 2026-09-22 live-probes (docs/SKILLS_LEDGER.md §0b) watched gemini-cli, claude-code, codex and agy each-activate all four routed bundles of a chair baseline unprompted and leave the control-alone — read from the CLI's own tool calls, not from atime. Skills are part of the-product now; measuring an effect is the A/B's job.--WHY ``C3D_SKILLS_ONLY`` exists. An effect A/B has to attribute its delta to ONE bundle,-and ``C3D_SKILLS=1`` routes up to five. Restricting the LIBRARY (rather than filtering-the selection afterwards) is the semantics that keeps the arms honest: the named bundle-is routed exactly where its own table rows fire, and the cap never silently drops it in-favour of a higher-priority sheet that is not under test. An unknown name yields an-empty library — every session then attaches nothing, which shows up immediately as a-variant arm identical to its control, rather than quietly measuring the full set.-"""--from __future__ import annotations--import logging-import os--from codeverse3d.config import env_flag--log = logging.getLogger(__name__)--SKILLS_ENV = "C3D_SKILLS"-SKILLS_MAX_ENV = "C3D_SKILLS_MAX"-SKILLS_UNVERIFIED_ENV = "C3D_SKILLS_UNVERIFIED"-SKILLS_ONLY_ENV = "C3D_SKILLS_ONLY"--DEFAULT_SKILLS_MAX = 5-def skills_enabled() -> bool:- """Is the skill system on for this process? Default ON since 2026-09-22; ``C3D_SKILLS=0``- (or ``off``) is the one way to turn it off — and a garbage value reads as off, never as- the variant (``config.env_flag``)."""- return env_flag(SKILLS_ENV, True)---def skills_unverified() -> bool:- """Route bundles whose evidence label is ``inherited-unverified``? Default yes since- 2026-09-22, so the whole library routes; the per-session cap (5) still holds."""- return env_flag(SKILLS_UNVERIFIED_ENV, True)---def skills_only() -> frozenset[str]:- """The bundles the router may consider, or empty for "all of them".-- Read at call time like the other three, for the same reason: an A/B arm sets it in- the child's environment and a value frozen at import would hand the variant the- control's library.- """- raw = os.environ.get(SKILLS_ONLY_ENV, "")- return frozenset(n.strip() for n in raw.split(",") if n.strip())---def skills_max(default: int = DEFAULT_SKILLS_MAX) -> int:- """Cap on bundles attached to one session. A bad value falls back, never crashes a run."""- raw = os.environ.get(SKILLS_MAX_ENV, "").strip()- if not raw:- return default- try:- n = int(raw)- except ValueError:- log.warning("%s=%r is not an integer; using %d", SKILLS_MAX_ENV, raw, default)- return default- if n < 0:- log.warning("%s=%d is negative; using 0", SKILLS_MAX_ENV, n)- return 0- return n---__all__ = ["DEFAULT_SKILLS_MAX", "SKILLS_ENV", "SKILLS_MAX_ENV", "SKILLS_ONLY_ENV",- "SKILLS_UNVERIFIED_ENV", "skills_enabled", "skills_max", "skills_only", "skills_unverified"]diff --git a/harness/codeverse3d/skills/materialize.py b/harness/codeverse3d/skills/materialize.pyindex 6bfd8d73..c5066c71 100644--- a/harness/codeverse3d/skills/materialize.py+++ b/harness/codeverse3d/skills/materialize.py@@ -40,7 +40,7 @@ from contextlib import suppressfrom pathlib import Pathfrom typing import Any-from codeverse3d.skills.config import SKILLS_ONLY_ENV, skills_max, skills_only, skills_unverified+from codeverse3d.config import get_settingsfrom codeverse3d.skills.model import Selection, Skill, SkillsMaterializedfrom codeverse3d.skills.prompting import (AGENTS_SKILL_ROOT,@@ -182,8 +182,8 @@ def attach_skills() -> SkillsMaterialized:"""Route → write → return what a session will see. The one entry point tracks call.- The caller decides whether the feature is on (``config.skills_enabled``); this- function assumes it is, so a test can attach without setting the environment.+ The caller decides whether the feature is on (``Settings.skills``); this function+ assumes it is, so a test can attach without setting the environment.``only`` (env ``C3D_SKILLS_ONLY``) restricts the LIBRARY before routing, which iswhat an effect A/B needs: the delta then belongs to one bundle instead of to whatever@@ -191,20 +191,21 @@ def attach_skills(filtering ``sel`` afterwards — also stops the cap from spending a slot on a bundlethat is not under test and then dropping the one that is."""- picked = skills_only() if only is None else only+ cfg = get_settings()+ picked = frozenset(n.strip() for n in cfg.skills_only.split(",") if n.strip()) if only is None else onlyif picked:from codeverse3d.skills import all_skillslib = dict(all_skills() if library is None else library)library = {n: s for n, s in lib.items() if n in picked}if not library:- log.warning("%s=%s matches no bundle in the library; this session attaches nothing",- SKILLS_ONLY_ENV, ",".join(sorted(picked)))+ log.warning("C3D_SKILLS_ONLY=%s matches no bundle in the library; this session attaches nothing",+ ",".join(sorted(picked)))sel: list[Selection] = select(track, language, kind,signals=plan_signals(plan), findings=findings, library=library,- max_skills=skills_max() if max_skills is None else max_skills,- allow_unverified=skills_unverified() if allow_unverified is None else allow_unverified,+ max_skills=cfg.skills_max if max_skills is None else max_skills,+ allow_unverified=cfg.skills_unverified if allow_unverified is None else allow_unverified,)out = SkillsMaterialized(listed=[s.name for s in sel], selections=list(sel),reasons={s.name: s.reason for s in sel}, attached_at=time.time())diff --git a/harness/codeverse3d/spatial/render_scene.py b/harness/codeverse3d/spatial/render_scene.pyindex f20ff174..e7f71ab6 100644--- a/harness/codeverse3d/spatial/render_scene.py+++ b/harness/codeverse3d/spatial/render_scene.py@@ -21,7 +21,7 @@ from collections.abc import Sequencefrom pathlib import Pathfrom typing import Any-from codeverse3d.config import env_flag, get_settings+from codeverse3d.config import get_settingsfrom codeverse3d.contracts.artifacts import RenderSet, RenderViewfrom codeverse3d.contracts.plan import BBox, CameraPlanfrom codeverse3d.conventions import SCENE_VIEWS, ViewPreset@@ -120,21 +120,21 @@ def run_scene_script(script: str, args: Sequence[str], *, timeout_s: float, cwd:def probe_env_args() -> list[str]:- """Scene-driver flags from the ``C3D_*`` switches — the ONE parser (review-3 S4),- on the canonical ``env_flag`` words, so ``C3D_CAMERA_REPAIR=false`` really- disables and ``C3D_AUTO_EXPOSURE=true`` really enables. Every driver- invocation — standalone probe, render, and the combined single-boot build —- appends these, so a census is always measured under the same settle /- camera-repair / auto-exposure policy the renders use."""+ """Scene-driver flags from the ``C3D_SETTLE`` / ``C3D_CAMERA_REPAIR`` /+ ``C3D_AUTO_EXPOSURE`` switches (``Settings``). Every driver invocation — standalone+ probe, render, and the combined single-boot build — appends these, so a census is+ always measured under the same settle / camera-repair / auto-exposure policy the+ renders use."""+ s = get_settings()args: list[str] = []- if not env_flag("C3D_SETTLE", True): # A/B switch for the boot-time auto-seat+ if not s.settle: # A/B switch for the boot-time auto-seatargs.append("--no-settle")- if env_flag("C3D_CAMERA_REPAIR", True): # default ON since 2026-08-30: pure insurance —+ if s.camera_repair: # default ON since 2026-08-30: pure insurance —# zero triggers across a whole healthy battery (scene_px_v1: layout camera-clearance# already keeps lenses out of furniture), and the one class it exists for# (fv_izakaya: three rounds of camera_in_geometry nobody could fix) is fatal.args.append("--camera-repair")- if env_flag("C3D_AUTO_EXPOSURE", False): # opt-in: bounded scene-wide exposure into the healthy band+ if s.auto_exposure: # opt-in: bounded scene-wide exposure into the healthy bandargs.append("--auto-exposure")return args@@ -145,7 +145,7 @@ def post_chain_args() -> list[str]:PICTURES only: object renders never touch this driver, and the scene probe runsraw because it is a 320x180 geometry instrument, not a judged frame. Kept outof :func:`probe_env_args` for exactly that reason."""- return [] if env_flag("C3D_POST", True) else ["--no-post"]+ return [] if get_settings().post else ["--no-post"]def _camera_json(cams: Sequence[CameraPlan]) -> str:diff --git a/harness/codeverse3d/tracks/articulated_object.py b/harness/codeverse3d/tracks/articulated_object.pyindex 279af1b0..ca38fb95 100644--- a/harness/codeverse3d/tracks/articulated_object.py+++ b/harness/codeverse3d/tracks/articulated_object.py@@ -9,12 +9,12 @@ renders a pose sheet which is appended to the judge's views.from __future__ import annotationsimport logging-import osimport timeimport xml.etree.ElementTree as ETfrom collections.abc import Sequencefrom pathlib import Path+from codeverse3d.config import get_settingsfrom codeverse3d.contracts.artifacts import (BuildResult,GateFinding,@@ -59,7 +59,7 @@ class ArticulatedPipeline(ObjectPipeline):def _axis_repair(ctx: RunContext) -> list[str]:"""Measure → deterministically fix wrong joint axes BEFORE the sweep renders,so this round's poses, renders and judge all see the corrected motion."""- if os.environ.get(AXIS_REPAIR_ENV) == "0":+ if not get_settings().axis_repair:return []try:pre = ctx.services.motion_checks(ctx.ws, ctx.plan)@@ -226,10 +226,6 @@ def axis_fix_hint(joint_name: str, axis: Sequence[float] | None, expected: str)return f"negate the <axis> of joint '{joint_name}' in src/robot.urdf (or swap lower/upper) so motion goes {expected}"-#: kill-switch for the deterministic axis repair (default ON, mirrors C3D_CAMERA_REPAIR)-AXIS_REPAIR_ENV = "C3D_AXIS_REPAIR"--def _set_axis_in_urdf_text(text: str, urdf_joint: str, axis: tuple[float, float, float]) -> str | None:"""``text`` with joint ``urdf_joint``'s ``<axis xyz>`` replaced (inserted whenmissing). String surgery instead of an XML round-trip so authored comments and@@ -285,7 +281,7 @@ def repair_motion_axes(ws: Workspace, report: GateReport | None) -> list[str]:authored file and the built ``artifacts/robot.urdf`` copy are updated so there-run gate and the pose sweep see the repair. Returns repaired plan-jointnames; a finding without measured data (``cos``) is never touched."""- if report is None or os.environ.get(AXIS_REPAIR_ENV) == "0":+ if report is None or not get_settings().axis_repair:return []src = ws.src / "robot.urdf"if not src.is_file():diff --git a/harness/codeverse3d/tracks/depth.py b/harness/codeverse3d/tracks/depth.pyindex 5908f338..bb0c4b87 100644--- a/harness/codeverse3d/tracks/depth.py+++ b/harness/codeverse3d/tracks/depth.py@@ -115,11 +115,11 @@ MIN_PARTS_FOR_SCOPED = 8DEFAULT_PARTS_PER_SCOPE = 3-def scoped_generation_enabled(default: bool = True) -> bool:- """``C3D_SCOPED_PARTS=off|0|false`` turns per-part scoped baselines off (A/B, debugging)."""- from codeverse3d.config import env_flag+def scoped_generation_enabled() -> bool:+ """``C3D_SCOPED_PARTS=off`` turns per-part scoped baselines off (A/B, debugging)."""+ from codeverse3d.config import get_settings- return env_flag("C3D_SCOPED_PARTS", default)+ return get_settings().scoped_parts@dataclass(frozen=True)diff --git a/harness/codeverse3d/tracks/generation.py b/harness/codeverse3d/tracks/generation.pyindex 074f4615..04a210c7 100644--- a/harness/codeverse3d/tracks/generation.py+++ b/harness/codeverse3d/tracks/generation.py@@ -34,7 +34,6 @@ attempt then raises. The label, round and outcome of each call are on the ledgefrom __future__ import annotationsimport logging-import osimport reimport shutilfrom collections.abc import Callable, Collection@@ -249,22 +248,14 @@ WRAPUP_PROMPT = (def agent_max_turns(default: int = DEFAULT_AGENT_MAX_TURNS) -> int:- """The turn cap a machine asks for: ``C3D_AGENT_MAX_TURNS`` >- ``Settings.limits.agent_max_turns`` > ``default``.+ """The turn cap a machine asks for: ``Settings.limits.agent_max_turns`` (also spelled+ ``C3D_AGENT_MAX_TURNS``) > ``default``.``0`` means *no cap*: the caller leaves ``AgentJob.max_turns`` at the backend'sown default. That is the measured default (docs/COST.md §17)."""- raw = os.environ.get("C3D_AGENT_MAX_TURNS", "").strip()- if raw.isdigit() and int(raw) > 0:- return int(raw)- try:- from codeverse3d.config import get_settings+ from codeverse3d.config import get_settings- configured = int(getattr(get_settings().limits, "agent_max_turns", 0) or 0)- except Exception as e: # noqa: BLE001 — settings must never break a generation- log.debug("agent turn cap fell back to the default: %s", e)- configured = 0- return max(0, configured or int(default))+ return get_settings().limits.agent_max_turns or max(0, int(default))def turn_capped(res: Any) -> bool:diff --git a/harness/codeverse3d/tracks/graphics.py b/harness/codeverse3d/tracks/graphics.pyindex 77ae64ea..56d11e43 100644--- a/harness/codeverse3d/tracks/graphics.py+++ b/harness/codeverse3d/tracks/graphics.py@@ -19,7 +19,7 @@ from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any-from codeverse3d.config import seed_recipes_enabled+from codeverse3d.config import get_settingsfrom codeverse3d.contracts.artifacts import (BuildResult,GateReport,@@ -250,7 +250,7 @@ def seed_recipes(ctx: RunContext) -> list[str]:(a resume appends only names the file does not define yet); return the names written THIS call.``ctx.extra["seeded_recipes"]`` lists every seeded recipe on disk (for the prompt block);``recipes.seeded`` is emitted with both. No-op unless glsl_shader and enabled."""- if ctx.language is not Language.GLSL_SHADER or not seed_recipes_enabled():+ if ctx.language is not Language.GLSL_SHADER or not get_settings().limits.seed_recipes:return []known = cookbook_functions(ctx.cookbook_text or "")chapters = recipe_chapters(ctx)diff --git a/harness/codeverse3d/tracks/plan_features.py b/harness/codeverse3d/tracks/plan_features.pyindex 536d8cc7..acdaa23b 100644--- a/harness/codeverse3d/tracks/plan_features.py+++ b/harness/codeverse3d/tracks/plan_features.py@@ -1,26 +1,42 @@-"""The A/B switch registry: which env switches any code path ACTUALLY reads.--Born as the switchboard for the plan-loop-engineering wave (CQ-5): six features were-declared under ``C3D_PLAN_FEATURES``, none was ever implemented, and one A/B run is on-record printing "keep, mean delta +0.344" for two byte-identical arms. The feature-runtime (``parse_features`` / ``plan_feature_on``) was deleted 2026-08-28 per its own-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 ``eval/bench/ab_plan.py`` consults so a paired A/B cannot-silently pin away the very thing it is testing.+"""What an A/B rig may assume about a ``C3D_*`` switch — ``eval/bench/ab_plan.py`` asks.++Eval-only: no runtime module imports this. Every switch the harness reads is a ``Settings``+field (``config.py``), so which names are live is derived from ``Settings.model_fields``+instead of a hand-kept list: an arm that differs only by a name no field reads is+byte-identical to its control (one A/B printed "keep, mean delta +0.344" for two such arms,+CQ-5), and ``ab_plan`` refuses it. ``pin_plan_blockers`` keeps ``--pin-plan`` from sharing+one plan across arms whose switch acts at or before planning."""from __future__ import annotations-PLAN_FEATURES_ENV = "C3D_PLAN_FEATURES"+from codeverse3d.config import Settings-#: 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-#: (eval/docs/EVAL.md §8.1 measured it — the A/A's worst pair differed 1 part vs 10).+#: switches that act AFTER planning — ``--pin-plan`` may share one plan across arms that+#: differ only by these. Anything else is treated as plan-side: refusing to pin costs one+#: noisy A/B, pinning wrongly costs a confident wrong answer (eval/docs/EVAL.md §8.1+#: measured it — the A/A's worst pair differed 1 part vs 10).GENERATION_SIDE_ENV: frozenset[str] = frozenset({"C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED","C3D_SKILLS_ONLY", "C3D_REFERENCE_DIFF", "C3D_SEED_RECIPES"})+#: the two the node side reads itself (runtime_js: gpu_launch.cjs, browser_daemon.cjs)+NODE_SIDE_ENV: frozenset[str] = frozenset({"C3D_BROWSER_REUSE", "C3D_PAGE_TTL_MS"})+++def _read(key: str) -> bool:+ """Does any ``Settings`` field — or the node side — read the environment variable ``key``?"""+ if key in Settings.FLAT or key in NODE_SIDE_ENV:+ return True+ section, _, name = key.removeprefix("C3D_").lower().partition("__")+ field = Settings.model_fields.get(section)+ if not name:+ return field is not None+ return field is not None and name in getattr(field.annotation, "model_fields", {})+++def dead_env_keys(env: dict[str, str]) -> list[str]:+ """The ``C3D_*`` keys of ``env`` that no Settings field reads — empty when the arm really+ differs. A key outside the ``C3D_`` family is not judged (it may matter to a CLI)."""+ return sorted(k for k in env if k.startswith("C3D_") and not _read(k))def pin_plan_blockers(variant_env: dict[str, str]) -> list[str]:@@ -28,53 +44,12 @@ 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, eval/docs/EVAL.md §8.1). A- :data:`DEAD_SWITCHES` key blocks nothing: no code reads it, so it cannot change a plan.+ planner's spread (the dominant variance term, eval/docs/EVAL.md §8.1). A dead key+ blocks nothing: no code reads it, so it cannot change a plan."""+ dead = set(dead_env_keys(variant_env))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.-LIVE_SWITCHES: dict[str, str] = {- "C3D_PLAN_BRIEF": "codeverse3d/tracks/planner.py", # brief.py merged in, 2026-08-28- # re-sample a degenerate plan from the original prompt instead of editing it in context- "C3D_PLAN_RESTART": "codeverse3d/tracks/planner.py",- "C3D_SCOPED_PARTS": "codeverse3d/tracks/depth.py",- "C3D_REFERENCE_DIFF": "codeverse3d/judges/vlm_judge.py", # reference.py merged in, 2026-08-28- # the skill system (design: scratchpad/skills/design/DESIGN.md §6.5). All three are- # read at call time by one module, so an A/B arm that sets them really differs.- "C3D_SKILLS": "codeverse3d/skills/config.py",- "C3D_SKILLS_MAX": "codeverse3d/skills/config.py",- "C3D_SKILLS_UNVERIFIED": "codeverse3d/skills/config.py",- "C3D_SKILLS_ONLY": "codeverse3d/skills/config.py",- "C3D_SEED_RECIPES": "codeverse3d/config.py",- # wire the scene texture pack into the scene loop: a stage before env/zones, and the- # pack description (texturing.plan.texture_pack_prompt) in both prompts. OFF by- # default — it costs an image-model call per run and nobody has measured what it buys.- "C3D_SCENE_TEXTURES": "codeverse3d/config.py",- # model-transport switches (2026-08-28, the hung-read waves): streaming with- # inter-chunk stall detection, and the IPv4-only transport. Read at call time- # by every gemini request, so a control arm can set either to 0.- "C3D_STREAM": "codeverse3d/models/gemini.py",- "C3D_IPV4": "codeverse3d/models/gemini.py",-}--#: Switches that are DECLARED but read by no code path, with the reason. An A/B arm that-#: differs only by one of these is byte-identical to its control, so ``ab_plan`` refuses-#: 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: "none of its six features was ever implemented; nothing reads this variable",- "C3D_DETAIL_ROUNDS": "the surface-detail round went with the judgement stops that offered it (2026-09-22)",- "C3D_FEWER_TURNS": "the fewer-turns bundle was deleted after its A/B read out flat (2026-09-22, COST §29)",-}---def dead_env_keys(env: dict[str, str]) -> list[str]:- """The keys of ``env`` that no code path reads — empty when the arm really differs."""- return sorted(k for k in env if k in DEAD_SWITCHES)+ if key not in GENERATION_SIDE_ENV and key not in dead]-__all__ = ["DEAD_SWITCHES", "GENERATION_SIDE_ENV", "LIVE_SWITCHES", "PLAN_FEATURES_ENV", "dead_env_keys",- "pin_plan_blockers"]+__all__ = ["GENERATION_SIDE_ENV", "NODE_SIDE_ENV", "dead_env_keys", "pin_plan_blockers"]diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.pyindex 999245d1..538cf4dc 100644--- a/harness/codeverse3d/tracks/planner.py+++ b/harness/codeverse3d/tracks/planner.py@@ -48,8 +48,6 @@ log = logging.getLogger(__name__)# ===================================================================== the brief-#: env switch: ``off``/``0``/``false`` disables brief expansion for the run-BRIEF_ENV = "C3D_PLAN_BRIEF"#: tracks the object-shaped brief applies to (graphics/scene get budgets only)BRIEF_TRACKS = (Track.STATIC_OBJECT, Track.ARTICULATED_OBJECT)BRIEF_TEMPLATE = "tracks/brief_object.j2"@@ -57,11 +55,11 @@ BRIEF_MAX_TOKENS = 65_536# ----------------------------------------------------------------------------- brief-def brief_enabled(spec: Spec, *, default: bool = True) -> bool:- """Whether to expand the brief for this spec (env switch wins; object tracks only)."""- from codeverse3d.config import env_flag # ONE flag vocabulary (review-3 S4)+def brief_enabled(spec: Spec) -> bool:+ """Whether to expand the brief for this spec (``C3D_PLAN_BRIEF``; object tracks only)."""+ from codeverse3d.config import get_settings- return env_flag(BRIEF_ENV, default) and spec.track in BRIEF_TRACKS+ return get_settings().plan_brief and spec.track in BRIEF_TRACKSdef brief_cache_dir() -> Path:@@ -594,8 +592,6 @@ MAX_QUALITY_REASKS = 1#: in context; at most this many times per plan. Measured 2026-09-02: 3-4 % of plan calls#: end this way, and both in-context re-asks reproduce the same broken plan verbatim.MAX_PLAN_RESTARTS = 1-#: kill-switch for that restart (default ON, mirrors C3D_AXIS_REPAIR)-PLAN_RESTART_ENV = "C3D_PLAN_RESTART"#: Output room for the plan call, sized from the plan budget. A deep plan is much longer#: JSON than a flat one AND Gemini 3.x bills its thinking against the same ceiling, so the#: flat 24 000 that served 8 box-parts truncates a 12-part plan with sub-parts —@@ -714,10 +710,10 @@ def restart_note(raw: Any, missing: list[str], budget: PlanBudget) -> str:def restart_enabled() -> bool:- """Kill switch for the degenerate-plan restart, ON by default (docs/COST.md §30)."""- from codeverse3d.config import env_flag # ONE flag vocabulary (review-3 S4)+ """Kill switch for the degenerate-plan restart (``C3D_PLAN_RESTART``, ON; docs/COST.md §30)."""+ from codeverse3d.config import get_settings- return env_flag(PLAN_RESTART_ENV, True)+ return get_settings().plan_restart#: an invalid plan attempt is written here, so a run that DIES at the plan stage still says@@ -1096,7 +1092,7 @@ def normalise_names[P: BaseModel](plan_obj: P) -> P:__all__ = ["MAX_PLAN_RESTARTS", "MAX_QUALITY_REASKS", "MAX_VALIDATION_REASKS",- "PLAN_RESTART_ENV", "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item",+ "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item","articulation_acceptance", "build_system_prompt", "build_user_prompt", "plan_event_stats","ensure_acceptance", "missing_link_names", "normalise_names", "plan","degenerate_plan", "plan_example", "plan_temperature", "plan_tokens", "restart_enabled",diff --git a/harness/codeverse3d/tracks/scene.py b/harness/codeverse3d/tracks/scene.pyindex c004b7cd..edbb5169 100644--- a/harness/codeverse3d/tracks/scene.py+++ b/harness/codeverse3d/tracks/scene.py@@ -26,7 +26,7 @@ import timefrom collections.abc import Callable, Sequencefrom typing import Any-from codeverse3d.config import scene_textures_enabled+from codeverse3d.config import get_settingsfrom codeverse3d.contracts.artifacts import (BuildResult,GateFinding,@@ -186,9 +186,7 @@ class SceneTrack(BaseTrack):# so the two stages' commits cannot race.def _layouts() -> dict[str, Any]:"""L2 zone layouts (optional accelerator): planner-model calls, never fatal."""- from codeverse3d.config import env_flag-- if not env_flag("C3D_ZONE_LAYOUTS", True): # A/B switch, default on; canonical words+ if not get_settings().zone_layouts: # C3D_ZONE_LAYOUTS: an A/B switch, default onreturn {}try:model = self._planner_model@@ -209,9 +207,9 @@ class SceneTrack(BaseTrack):# hit a stale cached stage. Old "assets+env" composite entries are ignored.key = {"plan": plan, "agent": ctx.agent_id}# textures first and alone: env and zones can only name the files if they exist by- # the time those prompts are built (config.scene_textures_enabled explains why this+ # the time those prompts are built (Settings.scene_textures says why this# is off by default and what it costs)- if scene_textures_enabled():+ if get_settings().scene_textures:ctx.extra["textures"] = runner.stage("textures", lambda: self._textures_stage(ctx), inputs={"plan": plan}) or {}stage_fns: dict[str, Any] = {"assets": lambda: run_asset_stage(ctx),"env": lambda: self._env_stage(ctx), "layouts": _layouts}diff --git a/harness/codeverse3d/tracks/skills_hook.py b/harness/codeverse3d/tracks/skills_hook.pyindex 86648231..514c299e 100644--- a/harness/codeverse3d/tracks/skills_hook.py+++ b/harness/codeverse3d/tracks/skills_hook.py@@ -6,8 +6,8 @@ workspace conventions, no environment) and testable without a run. Kept out ofEverything here is a no-op when ``C3D_SKILLS=0`` (the system is ON by default since2026-09-22), and every function swallows its own failures: a skill that cannot be routed,-written or probed must cost that skill, not the round. The switch is read at CALL time-(see ``skills/config.py`` for why). ``record_usage`` reads what the round's sessions did+written or probed must cost that skill, not the round. The switch is ``Settings.skills``,+read at the call. ``record_usage`` reads what the round's sessions didfrom their CLIs' own tool calls (``skills/telemetry.probe_reads``), atime only as fallback."""@@ -57,12 +57,13 @@ def _previous_findings(ctx: RunContext, index: int) -> list[GateReport]:def attach_for_round(ctx: RunContext, *, index: int, kind: str) -> Any | None:"""Route + materialise this round's skills. Returns the ``SkillsMaterialized``."""- from codeverse3d.skills import attach_skills, skills_enabled+ from codeverse3d.config import get_settings+ from codeverse3d.skills import attach_skills# drop the previous round's set first: a failure below must not leave this round# probing — and crediting — bundles it never attachedctx.extra.pop(CTX_KEY, None)- if not skills_enabled():+ if not get_settings().skills:return Nonetry:got = attach_skills(diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex cb11b6d0..385a4a51 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -75,7 +75,11 @@ codeverse3d/to_snake/to_pascal/slugify, MAX_TRIS_*, BBOX_TOLERANCE_M, CONTACT_GAP_M (THE source)config.py Settings (C3D_* env, ~/.config/3dcodeverse/config.yaml; role defaults come fromcontracts Backends; Settings.backends(**overrides) builds a Spec's Backends;- default_candidates=1)+ default_candidates=1). ONE switch grammar: every C3D_* knob is a field, read+ through get_settings() where it is used — no module reads the environment by+ hand; an on/off switch is a Flag (on/off/1/0/true/false/yes/no; a typo warns+ and keeps the default), Settings.FLAT holds the four flat spellings of nested+ knobs (C3D_MAX_IN_FLIGHT, C3D_RENDER_GPU, C3D_SEED_RECIPES, C3D_AGENT_MAX_TURNS)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, GateReport.of, BuildResult.gates, RenderView.judge,@@ -148,7 +152,8 @@ codeverse3d/(per-backend delivery policy + the index/mandate text),materialize.py,telemetry.py (the read probe: the CLIs' own tool calls first, atime as- fallback), config.py (call-time switches; skills ON by default since 2026-09-22)+ fallback); its switches are Settings fields (C3D_SKILLS*, ON by default since+ 2026-09-22)cost/ types.py (CallCost/Stage/Role) ledger.py (append-only telemetry/cost.jsonl + price provenance)context.py (per-call > ambient attribution) instrument.py (MeteredChatModel /MeteredAgent — one row per ChatModel.generate; one session row only for a backend@@ -197,9 +202,9 @@ codeverse3d/(C3D_PLAN_BRIEF), plan budgets and the worked examples — and the ONE owner ofwhat differs per track when planning: template, example, temperature, outputfloor, acceptance, all dispatched on spec.track),- 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),+ plan_features.py (eval-only: which C3D_* names are live, derived from+ Settings, and 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 under C3D_SKILLS=0; on by default since 2026-09-22)diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.mdindex cd2c8eae..31ff191a 100644--- a/harness/docs/INSTALL.md+++ b/harness/docs/INSTALL.md@@ -428,10 +428,14 @@ export C3D_LIMITS__AGENT_TIMEOUT_S=900export C3D_DEFAULT_CANDIDATES=2```-Three more are read directly by the runtime (not via `Settings`):-`C3D_RENDER_GPU` (`auto|on|off`, seen by the node/moderngl renderers),-`C3D_CACHE_DIR` (where `gpu_launch.cjs` puts the shared-browser endpoint file)-and `C3D_BROWSER_REUSE=off` (disable the shared headless-Chrome daemon).+Every knob the harness reads is a `Settings` field (`codeverse3d/config.py`, one+description each): `C3D_<FIELD>` at the top level, `C3D_<SECTION>__<FIELD>` nested, plus+four flat spellings of nested knobs — `C3D_MAX_IN_FLIGHT`, `C3D_RENDER_GPU`,+`C3D_SEED_RECIPES`, `C3D_AGENT_MAX_TURNS`. An on/off switch (`C3D_SKILLS`, `C3D_STREAM`,+`C3D_PLAN_BRIEF`, … — every `Flag` field) takes on/off, 1/0, true/false or yes/no in any+case; a typo warns and keeps the default, and an empty value is unset. The node side also+reads `C3D_RENDER_GPU` and `C3D_CACHE_DIR` itself, and one variable only it reads:+`C3D_BROWSER_REUSE=off` disables the shared headless-Chrome daemon.---diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex f0acb1b6..96fd0e1b 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -36,8 +36,9 @@ BuildResult.gates: list[GateReport] # the build's own reports (scene_probe + s# tracks/steps appends them to the round's gates, after the track's, built or notRenderView.judge: bool | None # stamped True/False at render time; None = legacy round (every stored view is judged)RenderSet.out_dir: str # directory the views (+ views.json/metrics.json) were written to ("" on old rounds)-from codeverse3d.config import get_settings, env_flag # env_flag(env, fallback) -> bool: on/off/1/0/true/false/yes/no;- # unset/empty -> fallback; garbage -> warning + False (off, NOT the fallback), never a crash+from codeverse3d.config import get_settings, Flag # every C3D_* switch is a Settings field (C3D_X -> .x,+ # C3D_S__X -> .s.x, Settings.FLAT for four flat spellings); Flag: on/off/1/0/true/false/yes/no, any case;+ # unset/empty -> the default; garbage -> warning + the DEFAULT, never a crashget_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@@ -476,7 +477,7 @@ from codeverse3d.tracks.prompting import select_cookbook_chapters, is_always_cha# select_cookbook_chapters(ctx, brief, *, budget=9000, always=COOKBOOK_ALWAYS) -> list[Section]: the header +# always-on chapters + the brief's chapters (whole, cookbook order, inside budget)from codeverse3d.tracks.graphics import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY, RECIPES_REL- # seed_recipes(ctx) -> list[str]: glsl_shader + seed_recipes_enabled() only. Writes the selected chapters'+ # seed_recipes(ctx) -> list[str]: glsl_shader + Settings.limits.seed_recipes only. Writes the selected chapters'# function definitions (minus always-on chapters and the raymarching template) + the helpers they call to# the HARNESS-OWNED src/recipes.glsl (RECIPES_REL; header "// harness-owned: … READ-ONLY …"; a resume appends# only names the file lacks); returns the names written THIS call; ctx.extra["seeded_recipes"] =diff --git a/harness/tests/conftest.py b/harness/tests/conftest.pyindex de6e54dd..ff4bdf4e 100644--- a/harness/tests/conftest.py+++ b/harness/tests/conftest.py@@ -23,6 +23,22 @@ def _fresh_settings():get_settings.cache_clear()+def switch(monkeypatch):+ """``switch("C3D_X", "off")`` sets (``None``: unsets) one variable and drops the cached+ Settings, so the next ``get_settings()`` reads it the way a fresh A/B child would."""+ from codeverse3d.config import get_settings++ def set_(name: str, raw: str | None) -> None:+ if raw is None:+ monkeypatch.delenv(name, raising=False)+ else:+ monkeypatch.setenv(name, raw)+ get_settings.cache_clear()++ return set_++@pytest.fixturedef tmp_ws(tmp_path: Path) -> Workspace:"""A fresh, git-initialised workspace under a temp dir."""diff --git a/harness/tests/core/test_config_env_aliases.py b/harness/tests/core/test_config_env_aliases.pyindex 3e4ca5c5..556c8e9d 100644--- a/harness/tests/core/test_config_env_aliases.py+++ b/harness/tests/core/test_config_env_aliases.py@@ -1,11 +1,52 @@-"""Flat environment aliases and layered configuration."""+"""One switch grammar, the flat spellings, and layered configuration."""from __future__ import annotations+import logging+import pytest+from pydantic import WrapValidatorfrom codeverse3d.config import Settings+#: every on/off switch, by the name an operator types (nested ones by their flat spelling)+_FLAGS = sorted([(f"C3D_{name.upper()}", field.default) for name, field in Settings.model_fields.items()+ if field.annotation is bool and any(isinstance(m, WrapValidator) for m in field.metadata)]+ + [("C3D_SEED_RECIPES", True)])+++def test_the_switches_are_the_ones_the_harness_reads():+ """A guard on the list the next test walks: every switch with its shipped default."""+ assert dict(_FLAGS) == {+ "C3D_AUTO_EXPOSURE": False, "C3D_AXIS_REPAIR": True, "C3D_CAMERA_REPAIR": True, "C3D_IPV4": True,+ "C3D_PLAN_BRIEF": True, "C3D_PLAN_RESTART": True, "C3D_POST": True, "C3D_REFERENCE_DIFF": True,+ "C3D_SCENE_TEXTURES": False, "C3D_SCOPED_PARTS": True, "C3D_SEED_RECIPES": True, "C3D_SETTLE": True,+ "C3D_SKILLS": True, "C3D_SKILLS_UNVERIFIED": True, "C3D_STREAM": True, "C3D_ZONE_LAYOUTS": True}++[email protected](("env", "default"), _FLAGS)+def test_every_switch_speaks_one_grammar(monkeypatch, caplog, env, default):+ """``C3D_STREAM=off``, ``C3D_IPV4=off`` and ``C3D_AXIS_REPAIR=off`` were silently ignored+ until 2026-09-22 (only "0" was read), fourteen switches were parsed by hand, and a typo+ in ``C3D_FEWER_TURNS`` crashed. Now: on/off, 1/0, true/false, yes/no in any case and+ padding; empty is unset; anything else warns and keeps the default (D44 c)."""+ def read(raw: str | None) -> bool:+ if raw is None:+ monkeypatch.delenv(env, raising=False)+ else:+ monkeypatch.setenv(env, raw)+ s = Settings()+ return s.limits.seed_recipes if env == "C3D_SEED_RECIPES" else getattr(s, env[4:].lower())++ assert read(None) is default and read("") is default+ for word in ("off", "0", "false", "no", "OFF", " Off "):+ assert read(word) is False, word+ for word in ("on", "1", "true", "yes", "ON"):+ assert read(word) is True, word+ with caplog.at_level(logging.WARNING, logger="codeverse3d.config"):+ assert read("maybe") is default+ assert env in caplog.text+def test_flat_and_nested_max_in_flight_aliases(monkeypatch):monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)@@ -18,12 +59,13 @@ def test_flat_and_nested_max_in_flight_aliases(monkeypatch):assert Settings().rate.max_in_flight == 8-def test_empty_alias_is_ignored_and_garbage_is_loud(monkeypatch):+def test_empty_is_unset_and_garbage_in_a_sizing_knob_is_loud(monkeypatch):+ """A cap is not a switch: an unparsable one stops the run before it starts."""monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "")assert Settings().rate.max_in_flight == 64monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "sixteen")- with pytest.raises(ValueError, match="C3D_MAX_IN_FLIGHT"):+ with pytest.raises(ValueError, match="max_in_flight"):Settings()@@ -40,7 +82,7 @@ def test_render_gpu_is_read_by_both_spellings_and_garbage_is_loud(monkeypatch):monkeypatch.setenv("C3D_RENDER__GPU", "off")assert Settings().render.gpu == "off"monkeypatch.setenv("C3D_RENDER_GPU", "maybe")- with pytest.raises(ValueError, match="C3D_RENDER_GPU"):+ with pytest.raises(ValueError, match="gpu"):Settings()@@ -48,7 +90,7 @@ def test_a_negative_cap_is_rejected_by_both_spellings(monkeypatch):"""Both spellings reject negative caps; zero remains the unlimited sentinel."""monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "-5")- with pytest.raises(ValueError, match="C3D_MAX_IN_FLIGHT"): # names the variable they typed+ with pytest.raises(ValueError, match="max_in_flight"):Settings()monkeypatch.delenv("C3D_MAX_IN_FLIGHT")monkeypatch.setenv("C3D_RATE__MAX_IN_FLIGHT", "-5")@@ -63,10 +105,11 @@ def test_the_rate_and_limits_dials_carry_their_bounds(monkeypatch):for kwargs in ({"max_in_flight": -1}, {"hedge": 0}):with pytest.raises(ValueError):Rate(**kwargs)- for kwargs in ({"max_parallel_agents": 0}, {"max_parallel_builds": -2}, {"agent_max_turns": -1}):+ for kwargs in ({"max_parallel_agents": 0}, {"max_parallel_builds": -2}):with pytest.raises(ValueError):Limits(**kwargs)assert Rate(max_in_flight=0).max_in_flight == 0, "0 stays legal: it means unlimited"+ assert Limits(agent_max_turns=-1).agent_max_turns == 0, "a switch: a bad cap warns and asks for none"# --------------------------------------------------------------------------- yaml layering@@ -104,6 +147,18 @@ def test_a_project_file_overrides_only_the_keys_it_names(tmp_path, monkeypatch):os.environ.pop("C3D_PROFILE", None)+def test_the_environment_beats_the_config_files_per_setting(monkeypatch):+ """docs/INSTALL.md §8.3 promises "... < project config < C3D_* env", but get_settings hands+ the yaml to Settings as init kwargs, which pydantic-settings ranked ABOVE the environment:+ a `skills: true` in a config file silently overrode an A/B arm's C3D_SKILLS=0 (the+ switches became Settings fields 2026-09-22, so this now decides A/B arms)."""+ for name, raw in (("C3D_SKILLS", "0"), ("C3D_RUNS_DIR", "/from_env"), ("C3D_JUDGE__SAMPLES", "3")):+ monkeypatch.setenv(name, raw)+ s = Settings(skills=True, runs_dir="/from_yaml", judge={"samples": 2, "max_px": 512})+ assert (s.skills, str(s.runs_dir), s.judge.samples) == (False, "/from_env", 3)+ assert s.judge.max_px == 512, "a yaml sibling the environment does not name survives"++def test_deep_merge_overlays_per_key_at_every_depth():from codeverse3d.config import _deep_mergediff --git a/harness/tests/install/test_docs.py b/harness/tests/install/test_docs.pyindex ba9fbf0b..894e6116 100644--- a/harness/tests/install/test_docs.py+++ b/harness/tests/install/test_docs.py@@ -232,7 +232,7 @@ def test_doctor_rows_have_troubleshooting_entries(monkeypatch) -> None:from codeverse3d.proc import ProcResultsettings = SimpleNamespace(- gemini_api_keys=("fake",), anthropic_api_key="", openai_api_key="",+ gemini_api_keys=("fake",), anthropic_api_key="", openai_api_key="", skills=False,rate=SimpleNamespace(max_in_flight=1),binaries=SimpleNamespace(node="node", gemini_cli="gemini", claude_cli="claude",codex_cli="codex", agy_cli="agy"),diff --git a/harness/tests/models/test_gemini.py b/harness/tests/models/test_gemini.pyindex 950493a7..93470154 100644--- a/harness/tests/models/test_gemini.py+++ b/harness/tests/models/test_gemini.py@@ -389,25 +389,28 @@ def test_drain_stream_cuts_a_stream_past_its_attempt_budget():assert e.value.retryable and "attempt budget" in str(e.value)-def test_streaming_toggle(monkeypatch):- from codeverse3d.models.gemini import _streaming_enabled-- monkeypatch.delenv("C3D_STREAM", raising=False)- assert _streaming_enabled()- monkeypatch.setenv("C3D_STREAM", "0")- assert not _streaming_enabled()---def test_ipv4_transport_toggle(monkeypatch):[email protected](("raw", "streamed"), [(None, True), ("0", False), ("off", False), ("OFF", False),+ ("on", True), ("garbage", True)])+def test_streaming_toggle(monkeypatch, switch, raw, streamed):+ """``C3D_STREAM=off`` was silently ignored until 2026-09-22: only "0" was read."""+ switch("C3D_STREAM", raw)+ calls: list[int] = []+ real = FakeModels.generate_content_stream+ monkeypatch.setattr(FakeModels, "generate_content_stream", lambda self, **kw: (calls.append(1), real(self, **kw))[1])+ m, _log, _ = make_model([text_response("hi")])+ assert m.generate(ChatRequest(messages=[ChatMessage.user("x")])).text == "hi"+ assert bool(calls) is streamed++[email protected](("raw", "bound"), [(None, True), ("0", False), ("off", False), ("no", False), ("1", True)])+def test_ipv4_transport_toggle(switch, raw, bound):+ """``C3D_IPV4=off`` was silently ignored until 2026-09-22: only "0" restored dual-stack."""import httpxfrom codeverse3d.models.gemini import _ipv4_client_args- monkeypatch.delenv("C3D_IPV4", raising=False)- args = _ipv4_client_args()- assert isinstance(args["transport"], httpx.HTTPTransport)- monkeypatch.setenv("C3D_IPV4", "0")- assert _ipv4_client_args() == {}+ switch("C3D_IPV4", raw)+ assert isinstance(_ipv4_client_args().get("transport"), httpx.HTTPTransport) is bounddef test_merge_stream_chunks_concatenates_text_and_keeps_final_usage():diff --git a/harness/tests/orchestrator_tracks/test_generation_depth.py b/harness/tests/orchestrator_tracks/test_generation_depth.pyindex a523226f..a467b22a 100644--- a/harness/tests/orchestrator_tracks/test_generation_depth.py+++ b/harness/tests/orchestrator_tracks/test_generation_depth.py@@ -72,12 +72,12 @@ def test_interfaces_text_names_only_the_neighbours_outside_the_scope(chair_plan)assert "no parts outside this scope" in empty-def test_scoped_generation_can_be_switched_off(monkeypatch):- monkeypatch.setenv("C3D_SCOPED_PARTS", "off")+def test_scoped_generation_can_be_switched_off(switch):+ switch("C3D_SCOPED_PARTS", "off")assert scoped_generation_enabled() is False- monkeypatch.setenv("C3D_SCOPED_PARTS", "on")+ switch("C3D_SCOPED_PARTS", "on")assert scoped_generation_enabled() is True- monkeypatch.delenv("C3D_SCOPED_PARTS")+ switch("C3D_SCOPED_PARTS", None)assert scoped_generation_enabled() is Truediff --git a/harness/tests/orchestrator_tracks/test_graphics_recipes.py b/harness/tests/orchestrator_tracks/test_graphics_recipes.pyindex e11ef80a..77f154a8 100644--- a/harness/tests/orchestrator_tracks/test_graphics_recipes.py+++ b/harness/tests/orchestrator_tracks/test_graphics_recipes.py@@ -8,7 +8,7 @@ from types import SimpleNamespaceimport pytest-from codeverse3d.config import Settings, seed_recipes_enabled+from codeverse3d.config import Settings, get_settingsfrom codeverse3d.contracts.common import HARNESS_OWNED_SRC, Language, Trackfrom codeverse3d.contracts.plan import GraphicsPlanfrom codeverse3d.languages import get_runtime@@ -25,7 +25,6 @@ from codeverse3d.languages.glsl_shader import (from codeverse3d.languages.glsl_shader import HEADER as WRAP_HEADERfrom codeverse3d.proc import EventLogfrom codeverse3d.prompts import load_text, render-from codeverse3d.tracks import graphics as grfrom codeverse3d.tracks.graphics import (HEADER,NOT_SEEDED,@@ -267,23 +266,27 @@ def test_resume_appends_only_new_names(tmp_path) -> None:def test_gate_and_language(tmp_path, monkeypatch) -> None:+ def seeding(raw: str | None) -> bool:+ if raw is None:+ monkeypatch.delenv("C3D_SEED_RECIPES", raising=False)+ else:+ monkeypatch.setenv("C3D_SEED_RECIPES", raw)+ get_settings.cache_clear()+ return get_settings().limits.seed_recipes+ws = _ws(tmp_path)- assert Settings().limits.seed_recipes is True and seed_recipes_enabled() is True- monkeypatch.setenv("C3D_SEED_RECIPES", "0")- assert seed_recipes_enabled() is False+ assert seeding(None) is True+ assert seeding("0") is Falsectx = _ctx(ws)assert seed_recipes(ctx) == [] and not _recipes(ws).exists() and "seeded_recipes" not in ctx.extraassert (ws.src / "common.glsl").read_text() == COMMON_GLSL and not _seeded_events(ws)- monkeypatch.setenv("C3D_SEED_RECIPES", "garbage")- assert seed_recipes_enabled() is False # a typo is a control run, not a crash- monkeypatch.setenv("C3D_SEED_RECIPES", "on")- assert seed_recipes_enabled() is True- monkeypatch.delenv("C3D_SEED_RECIPES")- monkeypatch.setattr(gr, "seed_recipes_enabled", lambda: True)+ assert seeding("garbage") is True # a typo keeps the default: never a crash, never the arm+ assert seeding("on") is True and seeding("off") is False+ assert seeding(None) is Trueassert seed_recipes(_ctx(ws, language=Language.OPENGL_PYTHON)) == [] # opengl_python: nothing seededassert not _recipes(ws).exists() and (ws.src / "common.glsl").read_text() == COMMON_GLSL- monkeypatch.setenv("C3D_SEED_RECIPES", "off")- assert Settings().limits.seed_recipes is False # the flat alias reaches Settings too+ monkeypatch.setenv("C3D_LIMITS__SEED_RECIPES", "off")+ assert Settings().limits.seed_recipes is False # the nested spelling reads the same field# ----------------------------------------------------------------------------- compose / lint / promptdiff --git a/harness/tests/orchestrator_tracks/test_plan_features.py b/harness/tests/orchestrator_tracks/test_plan_features.pyindex 82341572..341ac7f9 100644--- a/harness/tests/orchestrator_tracks/test_plan_features.py+++ b/harness/tests/orchestrator_tracks/test_plan_features.py@@ -1,59 +1,34 @@-"""``tracks/plan_features.py``: the switch registry that keeps A/B rigs honest about-which env switches any code actually reads (CQ-5)."""+"""``tracks/plan_features.py``: what an A/B rig may assume about a ``C3D_*`` switch (CQ-5).-from __future__ import annotations--from functools import cache-from pathlib import Path--import pytest--from codeverse3d.tracks import plan_features as F--# --------------------------------------------------------------------------- CQ-5-HARNESS = Path(__file__).resolve().parents[2]---@cache-def _sources() -> tuple[tuple[str, str], ...]:- """(relpath, text) for every harness source, read ONCE per session.-- Only ``codeverse3d`` counts: a switch is live when the HARNESS reads it. The evaluation- scripts (``eval/bench``) set switches for an A/B; they are not what makes one live.- """- out = []- for p in (HARNESS / "codeverse3d").rglob("*.py"):- if p.name != "plan_features.py":- out.append((str(p.relative_to(HARNESS)), p.read_text(errors="replace")))- return tuple(out)---def _readers(name: str) -> list[str]:- return [rel for rel, text in _sources() if name in text]--[email protected]("name", sorted(F.LIVE_SWITCHES))-def test_every_live_switch_is_really_read(name: str):- """A name in LIVE_SWITCHES that nothing reads is the CQ-5 bug all over again."""- readers = _readers(name)- assert readers, f"{name} is listed as live but no module reads it"- assert F.LIVE_SWITCHES[name] in readers, f"{name} is read by {readers}, not {F.LIVE_SWITCHES[name]}"--[email protected]("name", sorted(F.DEAD_SWITCHES))-def test_every_dead_switch_is_really_dead(name: str):- """The mirror guard: once something reads the variable, it must leave DEAD_SWITCHES —- otherwise ab_plan would refuse a legitimate A/B."""- assert not _readers(name), f"{name} is now read by {_readers(name)}; move it to LIVE_SWITCHES"+Which names are live is derived from ``Settings`` — every switch the harness reads is a+field there — so no list can drift from the code and no test has to grep the tree.+"""+from __future__ import annotations-def test_the_plan_features_switch_is_declared_dead():- """It is: none of its six features was ever implemented, so an arm that differs- only by C3D_PLAN_FEATURES is byte-identical to its control."""- assert F.PLAN_FEATURES_ENV in F.DEAD_SWITCHES- assert F.dead_env_keys({F.PLAN_FEATURES_ENV: "all"}) == [F.PLAN_FEATURES_ENV]- assert F.dead_env_keys({"C3D_PLAN_BRIEF": "off"}) == []- assert F.dead_env_keys({F.PLAN_FEATURES_ENV: "all", "C3D_PLAN_BRIEF": "off"}) == [F.PLAN_FEATURES_ENV]+from codeverse3d.config import Settings+from codeverse3d.tracks.plan_features import (+ GENERATION_SIDE_ENV,+ NODE_SIDE_ENV,+ dead_env_keys,+ pin_plan_blockers,+)+++def test_every_settings_field_is_a_live_switch_and_anything_else_is_dead():+ """An arm that differs only by a name nothing reads is byte-identical to its control+ (one A/B printed "keep, mean delta +0.344" for two such arms), so ab_plan refuses it.+ Every field, nested field, flat spelling and node-side name is live; the retired ones+ are dead the moment their field goes."""+ live = [f"C3D_{name.upper()}" for name in Settings.model_fields]+ live += [f"C3D_{section.upper()}__{name.upper()}" for section in ("rate", "render", "limits", "judge")+ for name in Settings.model_fields[section].annotation.model_fields]+ live += [*Settings.FLAT, *NODE_SIDE_ENV, *GENERATION_SIDE_ENV]+ assert dead_env_keys(dict.fromkeys(live, "1")) == []+ retired = ["C3D_PLAN_FEATURES", "C3D_FEWER_TURNS", "C3D_DETAIL_ROUNDS", "C3D_RATE__STORM_GATE",+ "C3D_RATE__TPM_PER_KEY", "C3D_MYSTERY_KNOB"]+ assert dead_env_keys({**dict.fromkeys(retired, "1"), "C3D_PLAN_BRIEF": "off"}) == sorted(retired)+ assert dead_env_keys({"GEMINI_CLI_HOME": "/x"}) == [], "outside the C3D_ family nothing is judged dead"# --------------------------------------------------------------------- pin-plan safety@@ -61,9 +36,7 @@ def test_a_generation_side_switch_may_share_one_plan():"""A switch that acts after planning cannot change the plan, so both arms can beseeded with the same plan.json and the paired delta stops carrying the planner'sspread — the dominant variance term (eval/docs/EVAL.md §8.1)."""- from codeverse3d.tracks.plan_features import pin_plan_blockers-- for name in sorted(F.GENERATION_SIDE_ENV):+ for name in sorted(GENERATION_SIDE_ENV):assert pin_plan_blockers({name: "1"}) == [], nameassert pin_plan_blockers({}) == []@@ -71,8 +44,6 @@ def test_a_generation_side_switch_may_share_one_plan():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"}) == []assert pin_plan_blockers({"C3D_PLAN_FEATURES": "all", "C3D_PLAN_BRIEF": "off"}) == ["C3D_PLAN_BRIEF is not known to act after planning"]@@ -80,11 +51,9 @@ def test_a_dead_switch_blocks_nothing_but_a_live_neighbour_still_does():def test_an_unclassified_switch_defaults_to_refusing():"""Refusing to pin costs one noisy A/B; pinning wrongly costs a confident wrong- answer. So the default for anything unknown is: do not pin."""- from codeverse3d.tracks.plan_features import pin_plan_blockers-- assert pin_plan_blockers({"C3D_MYSTERY_KNOB": "1"}) == [- "C3D_MYSTERY_KNOB is not known to act after planning"]+ answer. So anything live that is not known to act after planning refuses — a+ plan-side field, or a variable some CLI may read."""assert pin_plan_blockers({"C3D_PLAN_BRIEF": "off"}) == ["C3D_PLAN_BRIEF is not known to act after planning"]-+ assert pin_plan_blockers({"GEMINI_CLI_HOME": "/x"}) == [+ "GEMINI_CLI_HOME is not known to act after planning"]diff --git a/harness/tests/orchestrator_tracks/test_planner_depth.py b/harness/tests/orchestrator_tracks/test_planner_depth.pyindex 4ffefd1d..8928fa67 100644--- a/harness/tests/orchestrator_tracks/test_planner_depth.py+++ b/harness/tests/orchestrator_tracks/test_planner_depth.py@@ -274,13 +274,13 @@ def test_brief_failure_is_never_fatal(tmp_path):assert brief is None and usage.cost_usd == 0.0-def test_brief_switch_and_track_scope(monkeypatch):- monkeypatch.delenv(BR.BRIEF_ENV, raising=False)+def test_brief_switch_and_track_scope(monkeypatch, switch):+ switch("C3D_PLAN_BRIEF", None)assert BR.brief_enabled(_spec())assert not BR.brief_enabled(_spec(track=Track.GRAPHICS, language=Language.GLSL_SHADER))- monkeypatch.setenv(BR.BRIEF_ENV, "off")+ switch("C3D_PLAN_BRIEF", "off")assert not BR.brief_enabled(_spec())- monkeypatch.setenv(BR.BRIEF_ENV, "on")+ switch("C3D_PLAN_BRIEF", "on")assert BR.brief_enabled(_spec())@@ -340,8 +340,8 @@ def test_plan_output_room_grows_with_the_plan_and_is_capped():assert plan_tokens(small, 24000) >= 24000 # never below the caller's floor-def test_truncated_plans_keep_growing_output_room(tmp_path, monkeypatch):- monkeypatch.setenv(BR.BRIEF_ENV, "off")+def test_truncated_plans_keep_growing_output_room(tmp_path, switch):+ switch("C3D_PLAN_BRIEF", "off")from codeverse3d.models.base import ModelErrorgood = json.loads(_plan([_part(f"P{i}", desc=_detailed(i), material=f"m{i}") for i in range(9)]).model_dump_json())@@ -364,8 +364,8 @@ def test_truncated_plans_keep_growing_output_room(tmp_path, monkeypatch):assert len(got.parts) == 9-def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, monkeypatch):- monkeypatch.setenv(BR.BRIEF_ENV, "off")+def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, switch):+ switch("C3D_PLAN_BRIEF", "off")from codeverse3d.models.base import ModelErrorws = Workspace(tmp_path / "run")@@ -379,9 +379,9 @@ def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, monkeyp# ----------------------------------------------------------------------------- the loop-def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, monkeypatch):+def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, switch):"""A plan that never satisfies the gate is still USED — a mediocre plan beats no plan."""- monkeypatch.setenv(BR.BRIEF_ENV, "off")+ switch("C3D_PLAN_BRIEF", "off")ws = Workspace(tmp_path / "run")ws.create()thin = json.loads(_plan([_part(f"P{i}") for i in range(3)]).model_dump_json())@@ -400,8 +400,8 @@ def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, monkeypaassert len(got.parts) == 3 and ws.plan_path.is_file()-def test_a_good_plan_costs_exactly_one_call(tmp_path, monkeypatch):- monkeypatch.setenv(BR.BRIEF_ENV, "off")+def test_a_good_plan_costs_exactly_one_call(tmp_path, switch):+ switch("C3D_PLAN_BRIEF", "off")ws = Workspace(tmp_path / "run")ws.create()good = json.loads(_plan([_part(f"P{i}", desc=_detailed(i), material=f"m{i}") for i in range(9)]).model_dump_json())@@ -415,9 +415,9 @@ def test_a_good_plan_costs_exactly_one_call(tmp_path, monkeypatch):assert calls["n"] == 1 and len(got.parts) == 9-def test_brief_and_plan_are_one_model_and_the_events_say_so(tmp_path, monkeypatch):- monkeypatch.setenv(BR.BRIEF_ENV, "on")- monkeypatch.setenv("C3D_CACHE_DIR", str(tmp_path / "cache"))+def test_brief_and_plan_are_one_model_and_the_events_say_so(tmp_path, switch):+ switch("C3D_PLAN_BRIEF", "on")+ switch("C3D_CACHE_DIR", str(tmp_path / "cache"))ws = Workspace(tmp_path / "run")ws.create()good = json.loads(_plan([_part(f"P{i}", desc=_detailed(i), material=f"m{i}") for i in range(10)]).model_dump_json())diff --git a/harness/tests/orchestrator_tracks/test_planner_restart.py b/harness/tests/orchestrator_tracks/test_planner_restart.pyindex 3ae51780..f0c0ed6a 100644--- a/harness/tests/orchestrator_tracks/test_planner_restart.py+++ b/harness/tests/orchestrator_tracks/test_planner_restart.py@@ -11,12 +11,12 @@ import jsonimport pytest+from codeverse3d.config import get_settingsfrom codeverse3d.contracts.common import Language, Trackfrom codeverse3d.contracts.plan import ArticulatedPlanfrom codeverse3d.proc import EventLogfrom codeverse3d.tracks.planner import (MAX_PLAN_RESTARTS,- PLAN_RESTART_ENV,PlanningError,missing_link_names,plan,@@ -84,7 +84,7 @@ def test_an_ordinary_validation_error_still_edits_in_context(tmp_ws):def test_the_kill_switch_restores_the_in_context_reask(tmp_ws, monkeypatch):- monkeypatch.setenv(PLAN_RESTART_ENV, "0")+ monkeypatch.setattr(get_settings(), "plan_restart", False) # C3D_PLAN_RESTART=offp, model = _run(tmp_ws, [_degenerate(), _good()])assert isinstance(p, ArticulatedPlan) and len(model.requests[1].messages) == 3diff --git a/harness/tests/orchestrator_tracks/test_round_economics.py b/harness/tests/orchestrator_tracks/test_round_economics.pyindex 71fa0b43..3935d86d 100644--- a/harness/tests/orchestrator_tracks/test_round_economics.py+++ b/harness/tests/orchestrator_tracks/test_round_economics.py@@ -58,8 +58,8 @@ class _TurnAgent:usage=Usage(backend="api-agent", cost_usd=self.cost, input_tokens=1000))-def test_agent_sessions_are_uncapped_by_default(tmp_ws, monkeypatch):- monkeypatch.delenv("C3D_AGENT_MAX_TURNS", raising=False)+def test_agent_sessions_are_uncapped_by_default(tmp_ws, switch):+ switch("C3D_AGENT_MAX_TURNS", None)assert DEFAULT_AGENT_MAX_TURNS == 0agent = _TurnAgent(writes_on=1)task = GenerationTask(label="baseline", prompt="p", round=0, kind="baseline")@@ -67,11 +67,11 @@ def test_agent_sessions_are_uncapped_by_default(tmp_ws, monkeypatch):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 the machine's way of asking for one still works- monkeypatch.setenv("C3D_AGENT_MAX_TURNS", "9")+ switch("C3D_AGENT_MAX_TURNS", "9")assert agent_max_turns() == 9run_agent_task(tmp_ws, agent=agent, task=task)assert agent.jobs[-1].max_turns == 9- monkeypatch.setenv("C3D_AGENT_MAX_TURNS", "nonsense")+ switch("C3D_AGENT_MAX_TURNS", "nonsense") # warns, keeps the default: never a crashassert agent_max_turns() == DEFAULT_AGENT_MAX_TURNS == 0diff --git a/harness/tests/reference/test_judge_diff.py b/harness/tests/reference/test_judge_diff.pyindex 0c18cb9c..9a5ab3f5 100644--- a/harness/tests/reference/test_judge_diff.py+++ b/harness/tests/reference/test_judge_diff.py@@ -76,13 +76,14 @@ def test_diff_can_be_switched_off(ref_input, cache_dir):assert all(not r.label.startswith("reference_diff") for r in model.requests)[email protected]("value", ["off", "of"])-def test_diff_off_via_env(ref_input, cache_dir, monkeypatch, value):- """A typo is a control run, not the variant (config.env_flag): "of" used to read as ON."""- monkeypatch.setenv("C3D_REFERENCE_DIFF", value)- model = FakeChatModel(by_label={"judge": [good_reply(REF, ["A1", "A2"], 0.8)]})[email protected](("value", "diffed"), [("off", False), ("OFF", False), ("of", True)])+def test_diff_off_via_env(ref_input, cache_dir, switch, value, diffed):+ """``C3D_REFERENCE_DIFF=off`` switches the pass off; a typo warns and keeps the default+ (ON) — the arm that never set the switch, which is what D44 (c) asks of a typo."""+ switch("C3D_REFERENCE_DIFF", value)+ model = FakeChatModel(by_label={"reference_diff": [DIFF], "judge": [good_reply(REF, ["A1", "A2"], 0.8)]})_judge(model, cache_dir=cache_dir).judge(ref_input)- assert all(not r.label.startswith("reference_diff") for r in model.requests)+ assert any(r.label.startswith("reference_diff") for r in model.requests) is diffeddef test_best_view_iou_beats_a_fixed_front_view(ref_input, cache_dir, tmp_path):diff --git a/harness/tests/scene_gates/test_scene_textures_stage.py b/harness/tests/scene_gates/test_scene_textures_stage.pyindex 3318f48a..6e71fc80 100644--- a/harness/tests/scene_gates/test_scene_textures_stage.py+++ b/harness/tests/scene_gates/test_scene_textures_stage.py@@ -19,30 +19,19 @@ from __future__ import annotationsimport pytest-from codeverse3d.config import SCENE_TEXTURES_ENV, get_settings, scene_textures_enabled-from codeverse3d.tracks.plan_features import LIVE_SWITCHES+from codeverse3d.config import get_settings@pytest.fixture(autouse=True)def _clean_settings(monkeypatch):- monkeypatch.delenv(SCENE_TEXTURES_ENV, raising=False)+ monkeypatch.delenv("C3D_SCENE_TEXTURES", raising=False)get_settings.cache_clear()yieldget_settings.cache_clear()-def test_the_switch_is_off_by_default_and_readable_at_call_time(monkeypatch):- assert scene_textures_enabled() is False- monkeypatch.setenv(SCENE_TEXTURES_ENV, "1")- assert scene_textures_enabled() is True- monkeypatch.setenv(SCENE_TEXTURES_ENV, "false")- assert scene_textures_enabled() is False---def test_the_switch_is_registered_as_live():- """An A/B arm that differs only by a switch no code reads is byte-identical to its- control; `plan_features` refuses such an arm, and only if the name is declared."""- assert LIVE_SWITCHES[SCENE_TEXTURES_ENV] == "codeverse3d/config.py"+def test_the_switch_is_off_by_default():+ assert get_settings().scene_textures is Falsedef _render(name: str, **extra):diff --git a/harness/tests/scene_runtime/test_post.py b/harness/tests/scene_runtime/test_post.pyindex 071440c6..ef212e5b 100644--- a/harness/tests/scene_runtime/test_post.py+++ b/harness/tests/scene_runtime/test_post.py@@ -77,12 +77,12 @@ def render(ws: Workspace, out: Path, *extra_args: str) -> Path:return out / "cam_t0.png"-def test_post_chain_args_follow_the_env_switch(monkeypatch):- monkeypatch.delenv("C3D_POST", raising=False)+def test_post_chain_args_follow_the_env_switch(switch):+ switch("C3D_POST", None)assert post_chain_args() == [] # ON by default for scene pictures- monkeypatch.setenv("C3D_POST", "0")+ switch("C3D_POST", "0")assert post_chain_args() == ["--no-post"]- monkeypatch.setenv("C3D_POST", "on")+ switch("C3D_POST", "on")assert post_chain_args() == []diff --git a/harness/tests/scene_runtime/test_render_scene.py b/harness/tests/scene_runtime/test_render_scene.pyindex 8a37bdd4..2c30da14 100644--- a/harness/tests/scene_runtime/test_render_scene.py+++ b/harness/tests/scene_runtime/test_render_scene.py@@ -282,7 +282,7 @@ def _flags(args):def test_probe_env_args_speaks_the_canonical_flag_words(monkeypatch, env, expect):"""C3D_CAMERA_REPAIR=false must DISABLE, C3D_SETTLE=false must disable,C3D_AUTO_EXPOSURE=true must enable — the raw '0'/'1' compares silently- ignored every other word the doc'd env_flag vocabulary accepts."""+ ignored every other word of the documented on/off vocabulary (config.Flag)."""for k in ("C3D_SETTLE", "C3D_CAMERA_REPAIR", "C3D_AUTO_EXPOSURE"):monkeypatch.delenv(k, raising=False)for k, v in env.items():@@ -290,7 +290,7 @@ def test_probe_env_args_speaks_the_canonical_flag_words(monkeypatch, env, expectassert _flags(probe_env_args()) == expect-def test_every_driver_invocation_carries_the_env_flags(monkeypatch, ws, tmp_path):+def test_every_driver_invocation_carries_the_env_flags(monkeypatch, switch, ws, tmp_path):"""Review-3 S4 (V7c): the combined single-boot build probes under the SAMEsettle / camera-repair / auto-exposure flags as the standalone probe andrender paths — it used to pass none of them."""@@ -319,8 +319,8 @@ def test_every_driver_invocation_carries_the_env_flags(monkeypatch, ws, tmp_pathassert _flags(captured["render_scene.mjs"]) == ["--camera-repair"]# the A/B words reach every path, including the combined build- monkeypatch.setenv("C3D_SETTLE", "0")- monkeypatch.setenv("C3D_CAMERA_REPAIR", "false")+ switch("C3D_SETTLE", "0")+ switch("C3D_CAMERA_REPAIR", "false")st.probe_and_preflight(ws, timeout_s=5.0)assert _flags(captured["probe_scene.mjs"]) == ["--no-settle"]probes_mod.probe_scene(ws)diff --git a/harness/tests/skills/test_config.py b/harness/tests/skills/test_config.pyindex 015132f5..1ae8c29e 100644--- a/harness/tests/skills/test_config.py+++ b/harness/tests/skills/test_config.py@@ -1,4 +1,4 @@-"""The switches: read at call time, tolerant of garbage, and registered as LIVE.+"""The skill switches are ``Settings`` fields: ON by default, tolerant of garbage, live.``tracks/plan_features.py`` exists because a wave A/B'd a switch nothing read and printed"keep, mean delta +0.344" for two byte-identical arms. These tests are what keep@@ -9,61 +9,46 @@ from __future__ import annotationsimport pytest-from codeverse3d.skills import config as C-from codeverse3d.tracks import plan_features as F+from codeverse3d.config import Settings, get_settings+from codeverse3d.tracks.plan_features import dead_env_keys+++def _settings(monkeypatch, **env: str) -> Settings:+ for name in ("C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED"):+ monkeypatch.delenv(name, raising=False)+ for name, raw in env.items():+ monkeypatch.setenv(name, raw)+ return Settings()def test_on_by_default(monkeypatch):"""Flipped 2026-09-22 (owner): every backend is a vendor CLI with a native skill loader,and the whole library routes — the cap of 5 per session is the cost knob, not the switch."""- for env in (C.SKILLS_ENV, C.SKILLS_MAX_ENV, C.SKILLS_UNVERIFIED_ENV):- monkeypatch.delenv(env, raising=False)- assert C.skills_enabled() is True- assert C.skills_unverified() is True- assert C.skills_max() == C.DEFAULT_SKILLS_MAX == 5+ s = _settings(monkeypatch)+ assert (s.skills, s.skills_unverified, s.skills_max) == (True, True, 5)@pytest.mark.parametrize("raw, want", [("on", True), ("1", True), ("true", True), ("YES", True),- ("off", False), ("0", False), ("", True), ("maybe", False)])+ ("off", False), ("0", False), ("no", False), ("", True),+ ("maybe", True)])def test_flag_spellings(monkeypatch, raw, want):- """Unset or empty is the default (ON); garbage is OFF, never the variant — a typo in a- bench command must produce a control run (``config.env_flag``)."""- monkeypatch.setenv(C.SKILLS_ENV, raw)- assert C.skills_enabled() is want--[email protected]("raw", ["0", "off", "false", "no"])-def test_c3d_skills_0_turns_both_off(monkeypatch, raw):- """The ONE off switch an A/B control arm sets: nothing is enabled, whatever UNVERIFIED says."""- monkeypatch.setenv(C.SKILLS_ENV, raw)- monkeypatch.delenv(C.SKILLS_UNVERIFIED_ENV, raising=False)- assert C.skills_enabled() is False+ """Unset or empty is the default (ON); garbage warns and keeps the default — a typo in+ a bench command runs the arm that never set it, never a crash (D44 c)."""+ assert _settings(monkeypatch, C3D_SKILLS=raw).skills is wantdef test_unverified_can_still_be_turned_off(monkeypatch):- monkeypatch.setenv(C.SKILLS_UNVERIFIED_ENV, "0")- assert C.skills_unverified() is False---def test_read_at_call_time_not_cached(monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")- assert C.skills_enabled()- monkeypatch.setenv(C.SKILLS_ENV, "off")- assert not C.skills_enabled()+ assert _settings(monkeypatch, C3D_SKILLS_UNVERIFIED="0").skills_unverified is False[email protected]("raw, want", [("3", 3), ("0", 0), ("-1", 0), ("nope", 5), ("", 5)])[email protected]("raw, want", [("3", 3), ("0", 0), ("-1", 5), ("nope", 5), ("", 5)])def test_max_is_never_a_crash(monkeypatch, raw, want):- monkeypatch.setenv(C.SKILLS_MAX_ENV, raw)- assert C.skills_max() == want+ assert _settings(monkeypatch, C3D_SKILLS_MAX=raw).skills_max == want-def test_the_switches_are_registered_as_live_not_dead():- for env in (C.SKILLS_ENV, C.SKILLS_MAX_ENV, C.SKILLS_UNVERIFIED_ENV):- assert env in F.LIVE_SWITCHES, f"{env} must be declared so ab_plan accepts an arm using it"- assert env not in F.DEAD_SWITCHES- assert F.LIVE_SWITCHES[env] == "codeverse3d/skills/config.py"- assert F.dead_env_keys({C.SKILLS_ENV: "on"}) == []+def test_the_switches_are_live():+ assert dead_env_keys(dict.fromkeys(("C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED",+ "C3D_SKILLS_ONLY", "C3D_SKILLS_DIR"), "1")) == []def test_doctor_reports_the_default_and_the_gemini_pin(monkeypatch):@@ -71,9 +56,10 @@ def test_doctor_reports_the_default_and_the_gemini_pin(monkeypatch):must be pinned in the per-session system settings (a user file could turn it off)."""from codeverse3d.doctor import check_skills- monkeypatch.delenv(C.SKILLS_ENV, raising=False)+ monkeypatch.delenv("C3D_SKILLS", raising=False)rows = {name: status for name, status, _ in check_skills()}assert rows["skills switch"] == "OK" and rows["gemini-cli skills setting"] == "OK"assert rows["claude-code Skill tool"] == "OK"- monkeypatch.setenv(C.SKILLS_ENV, "0")+ monkeypatch.setenv("C3D_SKILLS", "0")+ get_settings.cache_clear()assert {name: status for name, status, _ in check_skills()}["skills switch"] == "WARN"diff --git a/harness/tests/skills/test_hook.py b/harness/tests/skills/test_hook.pyindex 338b82b5..a5dc233a 100644--- a/harness/tests/skills/test_hook.py+++ b/harness/tests/skills/test_hook.py@@ -13,7 +13,6 @@ from types import SimpleNamespace as NSimport pytestfrom codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity-from codeverse3d.skills import config as Cfrom codeverse3d.tracks import skills_hook as H@@ -38,7 +37,7 @@ def ctx(tmp_path: Path, library_dir: Path, monkeypatch):def test_the_switch_off_means_no_files_no_events_no_record(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "0") # ON is the default since 2026-09-22; off must be said+ monkeypatch.setenv("C3D_SKILLS", "0") # ON is the default since 2026-09-22; off must be saidassert H.attach_for_round(ctx, index=0, kind="baseline") is Noneassert not (ctx.ws.root / ".agents").exists()assert ctx.events == [] and ctx.extra == {}@@ -47,7 +46,7 @@ def test_the_switch_off_means_no_files_no_events_no_record(ctx, monkeypatch):def test_the_switch_on_attaches_records_and_measures(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")got = H.attach_for_round(ctx, index=0, kind="baseline")assert got and got.listedassert (ctx.ws.root / ".agents" / "skills" / got.listed[0] / "SKILL.md").is_file()@@ -60,7 +59,7 @@ def test_the_switch_on_attaches_records_and_measures(ctx, monkeypatch):def test_the_previous_rounds_findings_route_the_repair_sheet(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")rounds = ctx.ws.root / "rounds"rounds.mkdir()rec = {"index": 0, "kind": "baseline", "gates": [GateReport(@@ -78,13 +77,13 @@ def test_the_previous_rounds_findings_route_the_repair_sheet(ctx, monkeypatch):def test_round_zero_never_looks_for_a_previous_round(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")got = H.attach_for_round(ctx, index=0, kind="baseline")assert all(not s.gate_fired for s in got.selections)def test_repair_pointers_name_the_skill_that_answers_the_current_lint(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")H.attach_for_round(ctx, index=0, kind="repair")lint = GateReport(gate="lint:blender", passed=False, findings=[GateFinding(gate="lint:blender", severity=Severity.WARN,@@ -94,7 +93,7 @@ def test_repair_pointers_name_the_skill_that_answers_the_current_lint(ctx, monkedef test_single_shot_inlines_one_body_into_every_task(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")ctx.single_shot = Truegot = H.attach_for_round(ctx, index=0, kind="baseline")assert got.inlined and got.paths == []@@ -111,14 +110,14 @@ def test_single_shot_inlines_one_body_into_every_task(ctx, monkeypatch):def test_an_agent_session_never_gets_an_inlined_body(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")H.attach_for_round(ctx, index=0, kind="baseline")tasks = [NS(prompt="p")]assert H.with_inlined_skill(ctx, tasks) == tasksdef test_a_broken_library_costs_the_skills_not_the_round(ctx, monkeypatch, caplog):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")monkeypatch.setenv("C3D_SKILLS_DIR", "/definitely/not/a/directory")with caplog.at_level("WARNING"):got = H.attach_for_round(ctx, index=0, kind="baseline")@@ -127,7 +126,7 @@ def test_a_broken_library_costs_the_skills_not_the_round(ctx, monkeypatch, caplodef test_a_failed_attach_clears_the_previous_rounds_set(ctx, monkeypatch):"""Otherwise round N+1 probes round N's bundles and reports reads it never earned."""- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")assert H.attach_for_round(ctx, index=0, kind="baseline")monkeypatch.setattr("codeverse3d.skills.attach_skills",lambda *a, **k: (_ for _ in ()).throw(RuntimeError("boom")))@@ -136,7 +135,7 @@ def test_a_failed_attach_clears_the_previous_rounds_set(ctx, monkeypatch):def test_a_probe_failure_is_logged_not_raised(ctx, monkeypatch):- monkeypatch.setenv(C.SKILLS_ENV, "on")+ monkeypatch.setenv("C3D_SKILLS", "on")H.attach_for_round(ctx, index=0, kind="baseline")monkeypatch.setattr("codeverse3d.skills.telemetry.probe_reads", lambda *a, **k: (_ for _ in ()).throw(OSError("boom")))assert H.record_usage(ctx, index=0, kind="baseline") is Nonediff --git a/harness/tests/skills/test_loader.py b/harness/tests/skills/test_loader.pyindex 93a84e31..a41c0930 100644--- a/harness/tests/skills/test_loader.py+++ b/harness/tests/skills/test_loader.py@@ -132,8 +132,10 @@ def test_load_skill_by_name(tmp_path: Path):def test_the_library_dir_is_overridable_for_tests_and_the_live_smoke(tmp_path: Path, monkeypatch):- from codeverse3d.skills import SKILLS_DIR_ENV, skills_dir+ from codeverse3d.config import get_settings+ from codeverse3d.skills import skills_dirwrite_bundle(tmp_path, "c3d-demo")- monkeypatch.setenv(SKILLS_DIR_ENV, str(tmp_path))+ monkeypatch.setenv("C3D_SKILLS_DIR", str(tmp_path))+ get_settings.cache_clear()assert skills_dir() == tmp_pathdiff --git a/harness/tests/skills/test_only_switch.py b/harness/tests/skills/test_only_switch.pyindex 9cbe21f7..fb820f46 100644--- a/harness/tests/skills/test_only_switch.py+++ b/harness/tests/skills/test_only_switch.py@@ -10,7 +10,7 @@ from __future__ import annotationsimport pytest-from codeverse3d.skills.config import SKILLS_ONLY_ENV, skills_only+from codeverse3d.config import get_settingsfrom codeverse3d.skills.materialize import attach_skills@@ -66,20 +66,12 @@ def test_an_unknown_name_attaches_nothing_rather_than_everything(ws, caplog):"""A typo must make the variant visibly identical to its control, not silentlymeasure the full five-bundle set."""assert _listed(ws, only=frozenset({"c3d-typo"})) == []- assert SKILLS_ONLY_ENV in caplog.text+ assert "C3D_SKILLS_ONLY" in caplog.text-def test_the_switch_is_read_at_call_time(ws, monkeypatch):- """Frozen at import (the get_settings/lru_cache trap) the variant child would run the- control's library — the failure mode that printed 'keep, +0.344' for identical arms."""- monkeypatch.delenv(SKILLS_ONLY_ENV, raising=False)- assert skills_only() == frozenset()- monkeypatch.setenv(SKILLS_ONLY_ENV, " c3d-bbox-contract , ")- assert skills_only() == frozenset({"c3d-bbox-contract"})- assert _listed(ws) == ["c3d-bbox-contract"], "attach_skills must consult the env when only= is omitted"---def test_the_switch_is_registered_live():- from codeverse3d.tracks.plan_features import LIVE_SWITCHES-- assert SKILLS_ONLY_ENV in LIVE_SWITCHES, "an unregistered switch is one ab_plan calls dead"+def test_the_switch_reaches_the_router(ws, monkeypatch):+ """``only=`` omitted, attach_skills reads ``C3D_SKILLS_ONLY`` (a comma list, blanks+ ignored) — the variant child of an effect A/B sets nothing else."""+ monkeypatch.setenv("C3D_SKILLS_ONLY", " c3d-bbox-contract , ")+ get_settings.cache_clear()+ assert _listed(ws) == ["c3d-bbox-contract"], "attach_skills must consult the switch when only= is omitted"diff --git a/harness/tests/urdf_joints/test_axis_repair.py b/harness/tests/urdf_joints/test_axis_repair.pyindex f3c59704..6afcb16a 100644--- a/harness/tests/urdf_joints/test_axis_repair.py+++ b/harness/tests/urdf_joints/test_axis_repair.py@@ -3,6 +3,8 @@ from __future__ import annotationsimport xml.etree.ElementTree as ET+import pytest+from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severityfrom codeverse3d.tracks.articulated_object import MOTION_GATE, repair_motion_axesfrom codeverse3d.workspace import Workspace@@ -81,8 +83,10 @@ def test_warn_and_unknown_joints_are_skipped(tmp_path):assert _axis_of(ws, "Hinge") == (0.0, 0.0, -1.0)-def test_kill_switch_disables(tmp_path, monkeypatch):- monkeypatch.setenv("C3D_AXIS_REPAIR", "0")[email protected]("raw", ["0", "off", "false"])+def test_kill_switch_disables(tmp_path, switch, raw):+ """``C3D_AXIS_REPAIR=off`` was silently ignored until 2026-09-22: only "0" was read."""+ switch("C3D_AXIS_REPAIR", raw)ws = _ws(tmp_path)assert repair_motion_axes(ws, _report(_finding("Hinge", cos=-1.0))) == []assert _axis_of(ws, "Hinge") == (0.0, 0.0, -1.0)