Official Codebase of 3DCodeVerse
Python
docs: the map matches the code again, and D44 records what was rejected
gaoypeng3c24811edf06
diff --git a/harness/CLAUDE.md b/harness/CLAUDE.mdindex 0a99c28d..c5503492 100644--- a/harness/CLAUDE.md+++ b/harness/CLAUDE.md@@ -41,7 +41,7 @@ python **3.13** (one fixed version — owner's decision 2026-08-26; no floor, nonode **20.6+** · Blender 4.2+ · Linux x86_64. **There is no CI** (removed 2026-08-26 by theowner): run `ruff check codeverse bench tests` and the offline suite locally BEFORE everypush, with `set -o pipefail` so a `| tail` cannot swallow a red exit. The version lives in-`pyproject` `requires-python` + ruff `target-version` + `scripts/setup.sh`, and+`pyproject` `requires-python` + ruff `target-version` + `setup.sh`, and`spatial/node.py:NODE_MIN` + `runtime_js/package.json` `engines` for node, pinned together by`tests/core/test_portability.py`. Details: `docs/INSTALL.md` §2.1.@@ -100,8 +100,8 @@ cd /home/yipeng/3dcodeverse/harnesspython -m codeverse.judges.calibration runs/<slug>... --model gemini:gemini-3.1-pro-preview --n 3 --out out/python bench/complexity_report.py bench/out --recursive # score-vs-complexity + $/complexity point (docs/COMPLEXITY.md)python bench/compare_backends.py --prompts bench/prompts/compare_v1.yaml --arms harness:gemini-cli:gemini-3.6-flash,oneshot:claude-code --judge gemini:gemini-3.1-pro-preview --out bench/out/compare_v1-python -m pytest tests -q -m "not live" # 2 740 tests, ~37 s (real Blender + headless Chrome + CadQuery)-python -m pytest tests -q -m "not live and not blender and not node" # pure python: 2 627 tests, ~31 s+python -m pytest tests -q -m "not live" # 1 928 tests, ~58 s (real Blender + headless Chrome + CadQuery)+python -m pytest tests -q -m "not live and not blender and not node" # pure python: 1 809 tests, ~47 s# both run PARALLEL by default (pytest-xdist, -n auto --dist worksteal, in pyproject addopts).# A nested pytest inside a test MUST pass -n0 or it forks another full set of workers.```diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex b98e8a24..6eae7b7a 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -92,15 +92,16 @@ codeverse/2026-08-28, to the JSONL event log (Events), the run lock (ONE writer perrun dir: an fcntl.flock at <runs>/.locks/<slug>.lock whose record NAMES theholder, printed by `3dcv status`) and the bounded parallel fan-out- (fan_out, split_results, FanOutReport) — still a leaf: imports nothing- from codeverse+ (fan_out); sha256_file and version_line live here too — still a leaf:+ imports nothing from codeversemodels/ ChatModel (base.py), parts.py; gemini.py (the whole Gemini stack:request/response shapes, dead-key + free 429 rotation, the image model);anthropic.py openai.py (each with its own request/response shapes);- retry.py (the scheduling machine: key pool with 'dead' outcome + TPM- reservation/reconcile, rotation with MAX_WAIT_S ≤ 3 s single waits, the- shared 503 storm gate — ships OFF, docs/COST.md §21 — and the prompt-token- estimate); pricing.py (version-suffix-only fallback), health.py (preflight+ retry.py (the scheduling machine: KeyPool with outcomes ok | 429 | 5xx |+ error | dead | skip + TPM reservation/reconcile, StormGate — ships OFF,+ docs/COST.md §21 — with_retries / rotate_with_retries, both bounded by+ max_total_s ≤ RETRY_DEADLINE_S with MAX_WAIT_S ≤ 3 s single waits, and the+ prompt-token estimate); pricing.py (version-suffix-only fallback), health.py (preflightprobe: no retries, no backoff), schema_utils.py (strict schema), registry.pyagents/ registry.py (the CodingAgent protocol + dispatch — every backend is avendor CLI; the in-process api-agent died 2026-08-28), backends.py@@ -110,20 +111,26 @@ codeverse/languages/ LanguageRuntime (base.py); one merged module per language since 2026-08-28 —blender/ cadquery/ threejs/ urdf/ scene_threejs/ glsl_shader/ opengl_python/ are eacha single __init__.py (lint → skeleton → runtime, in dependency order) beside their- data (wrappers/, starter/, CONTRACT.md — Path(__file__) assets unchanged);+ data (wrappers/, starter/ — Path(__file__) assets unchanged; the contract text+ is prompts/<lang>/contract.md, read through RuntimeDocs);file_lint.py (one just-written file → syntax/lint verdict for write_file, COST.md §29)- spatial/ node.py, render.py, tool_common.py (shared tool plumbing),+ spatial/ node.py, render.py, observe.py, tool_common.py (shared tool plumbing),render_scene.py (judge view subset, content-fitted orbit),frame_metrics.py (scene_frames gate), frame_motion.py (measured inter-frame motion),scene_placement.py (scene_placement gate + check_placement tool: floating / sunken /unsupported / interpenetration per placed asset from the probe census's placementtable, runtime_js/lib/host_placement.mjs; added 2026-08-26),gl_render.py (GlHost), frame_stats.py (gl_frames),- sheet.py (montage_2x2, crop_region), turntable.py, measure.py, connectivity.py,+ sheet.py (montage_2x2, crop_region), measure.py, connectivity.py,contract.py (authoring-frame hints), sections.py, silhouette.py, probes.py,complexity.py (objective complexity vector -> Measurement.extra, docs/COMPLEXITY.md),joints*.py + joints_collide.py (deterministic penetration), registry.py,- tools.py (every @tool registration since 2026-08-28), mcp_server.py (MCP name: 3dcv)+ tools.py (every @tool registration since 2026-08-28, the joint_sweep body included;+ spatial siblings are plain imports — lazy() guards only codeverse.languages /+ codeverse.texturing and tool_common's node renderer), mcp_server.py (MCP name: 3dcv).+ Render modes are contracts.artifacts.RENDER_MODES (shaded wire normals silhouette+ clay — no 'depth'); build error_type spellings are languages/_common.MISSING_ENTRY+ ("MissingEntryFile") and BUILD_TIMEOUT ("BuildTimeout") for every runtimeskills/ registry.py (typed ROUTES + the router that evaluates them),model.py (Skill/Selection + the SKILL.md loader), prompting.py(per-backend delivery policy + the index/mandate text),@@ -138,22 +145,29 @@ codeverse/billing.py (SUBSCRIPTION_BACKENDS/bills_usd — which backends take real dollars,so the ledger bills real money and not list price; docs/COST.md §25)guard.py routing.py reconstruct.py (old runs) audit.py report.py- judges/ base.py (Judge protocol + the pure round-replay pieces `3dcv judge` and+ judges/ base.py (JudgeInput/Judgment helpers + the pure round-replay pieces `3dcv judge` andcalibration share), rubrics.py + rubrics/*.yaml (defect checklists, the wireschema, caps and scoring), prompt_builder.py (image prep, montages, thejudge messages), vlm_judge.py (+ the reference/likeness judges),- pairwise.py (compare_many), calibration.py- reference/ reference GROUNDING — give the pipeline a picture of what it is building:- one module: synthesis, THE plausibility gate that makes a synthesized+ pairwise.py (compare_many), calibration.py. No Judge Protocol: a judge is+ duck-typed `.judge(JudgeInput) -> Judgment`+ reference.py reference GROUNDING — give the pipeline a picture of what it is building:+ synthesis, THE plausibility gate that makes a synthesizedreference safe to use, Spec attachment + honesty guards, proportions(does the picture agree with the brief?), render-vs-reference diff,the content-addressed cache and ground_spec (the one call the CLI makes)texturing/ plan.py (VLM material plan + the scene texture pack), generate.py(generation + the tileable seam fix + the seam/judge gate), apply.py(world-metre unwrap, PBR map set, application + material normalisation),- materials.py (named material library), run.py (texture_pass)- orchestrator.py stage runner with resume, run state, round loop (RoundPolicy,- StopPolicy, BestSelector), refine-task compilation + grouping, budget+ materials.py (named material library), run.py (texture_pass); __init__.py is+ docstring-only — import from the submodules+ orchestrator.py the round loop's LIBRARY, not the loop: round POLICIES (RoundPolicy /+ StopPolicy / BestSelector), refine-task compilation + grouping,+ StageRunner + RunState (resume), BudgetGuard. The loop itself is+ tracks/lifecycle.py:_round_loop → tracks/steps.py:run_round. A best-of-N+ candidate IS steps._run_round(kind='candidate') in a _cand/c<k> sub-workspace+ with two knobs (render=candidates.quick_render, geometry_views=False), its+ own _cand/c<k>/events.jsonl and a one-sample judgetracks/ __init__.py (get_track(track, **options) + the TrackPipeline protocol),lifecycle.py, steps.py, candidates.py (best-of-N + the pure candidate/pairwisedecision logic), generation.py (agent + single-shot strategies + the file@@ -173,7 +187,7 @@ codeverse/depth.py,skills_hook.py (the round's view of codeverse/skills: attach before generating,probe reads after — a no-op unless CV3D_SKILLS is on)- flywheel/ record.py, export.py, pack.py, sample.py, pairs.py, migrate.py (schema moves),+ flywheel/ record.py (+ best_round_record), export.py, pack.py, sample.py, pairs.py,deliverable.py, telemetry.py, captions.py, quality.py (tiers + dedupe + code/mesh fingerprints), index.py,code_quality.py (the delivered CODE's own vector — magic numbers per 100 LOC,function length, dead functions, duplication, docstrings → record.extra@@ -236,9 +250,15 @@ runs/<slug>/src/ agent-authored RAW code (git repo; commits: spec, skeleton, pre:/agent:<label>, rNN <kind>)public/ (scene) compiled assets public/assets/<snake>.glb; (textured scenes) public/textures/*.png + manifest.json_assets/<snake>/ (scene) sub-workspaces for blender_glb assets (gitignored)- _cand/c<k>/ (--candidates N) throw-away best-of-N sub-workspaces (gitignored, kept for the flywheel)+ _cand/c<k>/ (--candidates N) throw-away best-of-N sub-workspaces (gitignored, kept for the flywheel):+ each is a round of kind "candidate" — its own events.jsonl, rounds/r00.json, gates/,+ judge/r00.json (one-sample judge on quick_render views)stages/<name>.json rounds/rNN.json rounds/candidates.json rounds/aborted_rNN.json (a round the- budget/a crash cut: what it burned, never resumed from) cost_ledger.jsonl (live ledger)+ budget/a crash cut: what it burned, never resumed from)+ telemetry/cost.jsonl live ledger: one row per metered call / CLI session, opened by BaseTrack.run+ (cost_ledger.jsonl at the root is a relative symlink to it, kept for the run-layout+ alias; runs before 2026-08-23 have the root file only)+ run_state.json stages + rounds done; extra carries budget_snapshot and spec_fingerprint onlyartifacts/ object.glb object.stl|step robot.urdf meshes/ articulation.json build.json census.jsonmeasurement.json … ; graphics: frames/fNN_tT.png frames_sheet.png preview.gif metrics.jsontexturing: object_textured.glb textures/{<id>.png, texture_plan.json, texturing.json, gate/}@@ -336,7 +356,8 @@ in-loop option with `n_samples ≥ 2` for decisions.```plan (structured output, one re-ask) → skeleton (buildable placeholder) → materialise workspace-[scene only] assets (parallel; blender_glb assets get a sub-workspace + asset_v1 judge + one fix pass)+[scene only] assets (parallel; blender_glb assets get a sub-workspace + asset_v1 judge + one fix pass; a degraded asset verdict leaves+ score None / judged False, emits asset.judge_degraded and skips the fix pass)→ env → zones (parallel) → assemble (deterministic scene.js)round 0 "baseline": generate → build_with_repair → measure → gates → render → post-render gates → judge(object tracks, ≥ 8 plan parts, a language with one file per part, an agent backend: the baseline FANS OUT@@ -355,7 +376,8 @@ repeat while StopPolicy says continue (≤ max_rounds refine rounds, plateau_winrefine tasks = gate ERRORS (fix hints, authoring-frame numbers) ∪ failed must-acceptance ∪ judge improvement plan(≤ 6 tasks, ≤ 6 compacted instruction lines each; reference runs add an IoU task when silhouette IoU < 0.6)fan out when ≥ 2 file-disjoint groups AND every task maps to files (threejs/blender parts, scene zones/assets/env)- generate (NO turn cap by default — 28 was A/B'd and rejected, +$0.02/−0.21 score, docs/COST.md §17;+ generate (no HARNESS turn cap by default — claude-code runs under AgentJob.max_turns=60 (+6-turn wrap-up),+ the other vendor CLIs have no turn cap at all; 28 was A/B'd and rejected, +$0.02/−0.21 score, docs/COST.md §17;a cap a caller sets (CV3D_AGENT_MAX_TURNS / task; no profile sets one) still buys a wrap-up sessionthat lands a final build + summary instead of being killed) → build+repair (error-focused,escalates on identical signatures) → gates → … → judge (SKIPPED only where the verdict is never@@ -448,8 +470,8 @@ $0.02–0.03 (flash) / ~$0.2 (pro); api-agent generation 3–6 min per object rotrips the budget is not promoted to best — give scenes `--max-minutes 60`.* Gemini flash 503 storms happen; dead keys and 429s rotate freely now, but asustained outage can still fail a round (`3dcv resume` re-uses cached stages).-* `ffmpeg` absent here → turntables fall back to GIF. A few single-file wrappers- were once over the old ~400-line guideline; the rule is now a 2 000-line cap (3 000 absolute).+* A few single-file wrappers were once over the old ~400-line guideline; the rule+ is now a 2 000-line cap (3 000 absolute).## 11. Flywheeldiff --git a/harness/docs/COST.md b/harness/docs/COST.mdindex 6b193406..f3a1cd26 100644--- a/harness/docs/COST.md+++ b/harness/docs/COST.md@@ -287,9 +287,11 @@ made:**| verified (no change) | – | every other gemini / anthropic / openai row | now flagged `verified` rather than "approximate" || still `inferred` / `unverified` | – | `claude-haiku-4`, `o1-mini`, `gpt-5-codex`, `gpt-5.1-codex`, `gpt-5.2-codex`, `gemini-2.5-flash-image` | not listed on the pricing pages; `3dcv cost prices --unverified` lists them |-Per-image prices now live in the price table (`Price.image_usd`,-`IMAGE_USD_BY_SIZE`, `per_image_usd()`), and a test asserts they never drift from-`models/gemini_image.IMAGE_USD`.+Per-image prices live in the price table only (`Price.image_usd`,+`IMAGE_USD_BY_SIZE`, `per_image_usd()`); the duplicate table in the image model is+gone (2026-08-29) and `GeminiImageModel` prices with `per_image_usd(size=<generated+px>)` directly — a 2K image was billed 0.067 (the 1K rate) instead of 0.134 until then,+and a 512 request is billed as the 1K image it actually generates.**Two costing bugs the audit surfaced** (both in files owned by other engineers —see the hand-off notes):@@ -349,7 +351,7 @@ Savings are estimated **on this data set** (61 runs, $86.30) unless stated.| # | change | est. saving | confidence | where ||---|---|---|---|---|| 1 | **Stop refining after r01 unless the last delta ≥ 0.05.** r02+r03 cost $12.16 and bought +1.44 score points across 8 of 20 rounds. | **$9–12 (10–13%)** | high (measured) | `RoundPolicy` (min_delta 0.02 → 0.05 from r02, or plateau_window 1 after r01) |-| 2 | **Check the budget *before* starting a round, against the estimated round cost**, not only between steps. | **$8.76 (9.7%)** | high (measured waste) | `orchestrator/budget.py` + `tracks/steps.py`; use `codeverse.cost.estimate_call` / median round cost |+| 2 | **Check the budget *before* starting a round, against the estimated round cost**, not only between steps. | **$8.76 (9.7%)** | high (measured waste) | `orchestrator.py` (`BudgetGuard`) + `tracks/steps.py`; use `codeverse.cost.estimate_call` / median round cost || 3 | ~~**Cap agent turns at ~25 and compact old tool results.** 39.3% of the agent bill is turn ≥20; 19 of the 33 sessions that ran ≥50 turns were cut off by their own budget.~~ **Tested, rejected: +$0.02 and −0.21 score** (A/B, n=3 per arm, §17) — the cap is off by default. | est. $8–15, **measured $0** | high (A/B) | `RoundPolicy.agent_max_turns=0`; still settable per caller || 4 | **Fold the off-record spend into the budget** (cut rounds, post-hoc texture passes). | $0 saved, **$1.22 of blindness removed** | high | §6; the ledger (`codeverse.cost.record_call`) makes it automatic || 5 | **Scene track: 73% of scene spend is assets+zones, 0/5 passed.** Trim the per-zone context (each zone session re-sends the whole scene contract) and judge assets before zones start. | ~$1/run of $2.83 | medium | `tracks/scene*.py` |@@ -370,11 +372,11 @@ the model, is what makes the artifact), and cheaper judges (§8).```pythonfrom codeverse.cost import record_call, load_ledger, summarise-record_call(res.usage, run=ws.slug, round=idx, stage="refine", role="generator",- label=job.label, outcome=res.exit_reason,- ledger=ws.root / "cost_ledger.jsonl") # one append-only JSONL row+with run_ledger(ws.root): # <run>/telemetry/cost.jsonl (cost_ledger.jsonl = symlink alias)+ record_call(res.usage, run=ws.slug, round=idx, stage="refine", role="generator",+ label=job.label, outcome=res.exit_reason) # one append-only JSONL row-rows = load_ledger(ws.root / "cost_ledger.jsonl")+rows = load_ledger(ws.root) # telemetry/cost.jsonl, else the pre-2026-08-23 root filesummarise(rows).dimension("stage")["judge"].cost_usd```@@ -434,9 +436,7 @@ out not to pay.captioner, texturing and single-shot generation.* **`MeteredAgent`** wraps everything `agents.get_coding_agent` hands out: it setsthe ambient round/stage for the session (so the rows above land in the right- bucket), applies whatever turn cap the settings name (only ever *lowering*- `job.max_turns`; no profile names one — §17)- and, for a backend whose calls we cannot see (gemini-cli / claude-code / codex /+ bucket) and, for a backend whose calls we cannot see (gemini-cli / claude-code / codex /agy), records one session row from `AgentResult.usage`.**Which backends those are is a property of the backend, not a guess.** The@@ -457,7 +457,14 @@ label that names a job of its own (`judge:…`, `planner`, `texture_gate`,bills a model inside a refine session used to land on `stage=refine /role=generator`; it now lands on its own stage. A *generation* label still yieldsto the session, which knows more (best-of-N runs `job.kind="candidate"` while the retired api-agent's-recorded turns were labelled `api-agent:baseline:tN`).+recorded turns were labelled `api-agent:baseline:tN`). A session row is filed by the task+KIND through `cost.types.stage_for_label` (candidate → candidate, zone → zones, compose →+assemble, rebuild → repair, asset / asset_fix → assets); before 2026-08-29 the scene kinds+landed in `other`. Candidate generation sessions carry `stage=candidate` with labels+`baseline_c<k>`; candidate judge money is booked `stage=judge role=judge round_index=0`+and the pairwise tie-break `stage=judge label=pairwise`. `audit.lost_candidate` counts+generator sessions only and reads both label forms — `baseline_c<k>` (live) and+`c<k>:baseline` (reconstructed).**Who opens a ledger.** `3dcv make` / `3dcv resume` (`cli.main._run_track`),`3dcv texture pass` (with `create=False`), **and the bench drivers** —@@ -482,9 +489,12 @@ working — one physical copy. A call made with no run context (a `3dcv judge`outside a run, a bench script, a notebook) goes to a per-process log under`<cache_dir>/cost/`; `CV3D_COST_LEDGER=off` disables writing entirely.-**No double counting.** `BudgetGuard.spend` also knows how to write rows; while-`cost.instrument.per_call_metering()` is true it skips its own, because the-per-call rows *are* that dollar with the tokens, cache hits and latency attached.+**No double counting.** `BudgetGuard` only buckets and enforces; `MeteredAgent` /+`MeteredChatModel` are the one writer of `telemetry/cost.jsonl`, and `BaseTrack.run`+opens the run ledger itself. The guard's own aggregate writer and its+`per_call_metering()` sentinel were deleted 2026-08-29: every production entry point+(`3dcv make`, the bench drivers) opened `run_ledger` first, so it never wrote there —+and with `CV3D_COST_LEDGER=off` it wrote anyway, which is now really off.**Reading it.** `cost.reconstruct.reconstruct_run` prefers a live ledger andfalls back to rebuilding from trajectories / verdicts / events, so@@ -1241,8 +1251,9 @@ sessions overshot their timeout by 182 s median / 1 154 s p90); a judge sample g`SAMPLE_BUDGET_S = 240` for all its attempts (the verdict is 42 s p50 / 73 s p90, 50 / 103 s underthe storm; two rounds lost 1 162 s and 927 s to 3 × 300 s timeouts before a second sample answeredin 128 s); the planner 300 s (13.7 s p50 / 32 s p90, max 76 s; the storm-day plan stage waited-492 s median for 39 s of model time). Anthropic / OpenAI go through `with_retries`, which has no-deadline (≈ 20 s of backoff at most), so the field is a no-op there.+492 s median for 39 s of model time). Anthropic / OpenAI go through `with_retries`, which+since 2026-08-29 takes the same `max_total_s = ChatRequest.max_wait_s` (clipped to+`RETRY_DEADLINE_S`) and stamps `ModelError.attempts` — the field is honoured on every provider.*The retry of a 503 is hedged across keys* (`rotate_with_retries(hedge=2)`; `Settings.rate.hedge`,diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.mdindex 0359df23..01d5d843 100644--- a/harness/docs/DECISIONS.md+++ b/harness/docs/DECISIONS.md@@ -51,21 +51,29 @@ written) that were accepted because the code works that way and the tests pin itrestored from `run_state.extra.budget_snapshot` (`BudgetSnapshot`: spent usage, billedUSD, call count, per-stage/per-round buckets, cumulative ACTIVE seconds — grace isdeliberately NOT persisted). Prior spend and active minutes still count after a- resume, so a raised `--max-minutes` grants only the difference; `spent_usage` is mirrored- for one release, and old run dirs without a snapshot fall back to it (spent only).+ resume, so a raised `--max-minutes` grants only the difference. The `spent_usage`+ mirror in `run_state.extra` was dropped 2026-08-29 (write side); the read fallback+ stays because 531 of 739 `bench/out` run dirs predate `budget_snapshot`.+ `run_state.extra` carries `budget_snapshot` and `spec_fingerprint` only: the+ candidate count lives in `spec.options.candidates`, the candidate table in+ `rounds/candidates.json` (which `record.extra.candidates` is read from).* **D8 Events carry `event`, not `kind` (Δ).** `EventLog.emit(event, **data)` so payloadsmay include `kind=` (round kind). `3dcv status` and tests follow.-* **D9 `materialize_workspace` returns `Materialized` (Δ).** Callers need codex `-c`- overrides and the agy fallback text; callers that ignore the return are unaffected.+* **D9 `materialize_workspace` returns `Materialized` (Δ).** Body files, ignore files,+ the cookbook path, the MCP command and warnings; callers that ignore the return are+ unaffected. The codex `-c` overrides are NOT on it (`codex_overrides` was deleted+ 2026-08-29): the codex backend builds `codex_mcp_overrides(mcp_command)` per session.The cookbook is copied to `ws/.3dcv/cookbook.md` (gemini-cli cannot read outside the- workspace); MCP argv uses `sys.executable`.+ workspace); the MCP argv defaults to `cli_common.default_mcp_command(ws)`, i.e.+ `sys.executable`, for every backend (the track-side bare-`python` literals are gone).* **D10 gemini-cli needs a system-settings file (Δ).** api-key auth +`dynamicModelConfiguration` (else silent model substitution) + `folderTrust.enabled=false`(else workspace MCP servers are silently disabled even with `--skip-trust`). Servedmodel is checked; mismatch → `exit_reason=model_substituted`.-* **D11 AgentJob carries typed fields; `extra` is back-compat only (Δ, revised 2026-08-27).**- `round`, `kind`, `files_hint`, `language`, `track` are typed `AgentJob` fields;- `contracts/agent.py::_lift_legacy_extra` lifts old `extra` payloads into them.+* **D11 AgentJob carries typed fields only (Δ, revised 2026-08-29).**+ `round`, `kind`, `files_hint`, `language`, `track`, `read_only`, `mcp_command` … are+ typed `AgentJob` fields; the `extra` dict and its `_lift_legacy_extra` shim (and the+ unused `model` field) were deleted 2026-08-29 — nothing in the tree built one.* **D12 api-agent exposes `build` under its real name; `run_build` is an alias (Δ).*** **D13 Node ESM resolution via an import hook (Δ).** `NODE_PATH` cannot resolve bare ESMspecifiers; `run_node(three_hook=True)` adds `--import runtime_js/lib/resolve_three.mjs`;@@ -233,7 +241,30 @@ written) that were accepted because the code works that way and the tests pin itgenerated bpy file made CPython 3.11's `ast.parse` raise `SystemError` and the round diedin `build_once`. Decision: `_ast_lint.safe_parse` catches SyntaxError / RecursionError /SystemError / MemoryError / ValueError; every python lint reports a lint ERROR with a- flatten-the-literal hint instead.+ flatten-the-literal hint instead. The forbidden-import floor is one set:+ `_ast_lint.BASE_FORBIDDEN_IMPORTS` (pickle, threading, importlib, webbrowser, ftplib,+ smtplib, …) — since 2026-08-29 urdf's `model.py` lint is on it too (those became+ ERRORs there) plus an explicit allow-list `{bpy, bmesh, mathutils, math, random, numpy}`;+ anything else imported is a WARN, a `codeverse` self-import an ERROR.+* **D44 The 2026-08-29 cleanup: delete, do not relocate (owner).** Context: an external+ review of `codeverse` proposed executor / policy abstractions (a `RoundExecutor`, a+ `CandidateRunner`, a metering seam, a per-track prompt-policy object). Decision: all+ rejected — each moved code between files without deleting any (L4: a merge must delete).+ What was done instead: (a) **candidates are rounds** — `run_candidate` / `quick_judge`+ went, a best-of-N candidate is `steps._run_round(kind="candidate")` in its sub-workspace+ with two knobs (`render=quick_render`, `geometry_views=False`), its own `events.jsonl`+ and a one-sample judge; (b) **one ledger writer** — `BudgetGuard` buckets and enforces+ only, `MeteredAgent` / `MeteredChatModel` write `telemetry/cost.jsonl`, and+ `BaseTrack.run` opens the run ledger itself (`per_call_metering`, `_ledger_row`,+ `run_ledger_path` deleted; `CV3D_COST_LEDGER=off` now really writes nothing);+ (c) **a garbage env flag is OFF** — `config.env_flag` reads on/off/1/0/true/false/yes/no;+ unset or empty is the caller's fallback (usually the Settings value), but an unparseable+ value warns and reads as OFF, so a typo in a bench command is a control run, never a+ silent arm (and never the variant, which a fallback of `True` would have handed it); (d) one MCP command (`default_mcp_command`, `sys.executable`),+ one JSON-envelope finder, one union-find, one sha256, one `ask_structured`, one+ `RENDER_MODES`; the retired mechanisms (`3dcv migrate-runs`, turntables + ffmpeg, the+ `CV3D_SYSPROMPT=v0` arm, `shader_presence` / counterfactual renders, the in-process+ turn-cap backstop, the concurrent-session registry) are gone with their docs.## Rejected / deferreddiff --git a/harness/docs/EVAL.md b/harness/docs/EVAL.mdindex 9a33c0df..121a4132 100644--- a/harness/docs/EVAL.md+++ b/harness/docs/EVAL.md@@ -526,9 +526,18 @@ under `bench/out/`.## Judge experiments log+**2026-08-29 — profiles and the detail round.** `RoundPolicy.detail_rounds` is tri-state+(`None` = the track default, `lifecycle.DEFAULT_DETAIL_ROUNDS=1` where supported; `0` = off).+Until this date a profile that injected a `judge_samples>1` policy (economy, quality)+silently zeroed the static track's surface-detail round while balanced kept it; all+three profiles now get it, and `CV3D_DETAIL_ROUNDS` remains the A/B switch. Any+economy/quality-vs-balanced comparison straddling this commit compares different+round counts.+**2026-08-29 — per-language system prompts: NULL, three independent A/Bs.** Theone-line system prompts were replaced with evidence-grounded ones mined from each-language's recorded failure corpus (`CV3D_SYSPROMPT=v0` keeps the old ones). Three+language's recorded failure corpus (the `CV3D_SYSPROMPT=v0` arm kept the old ones for+the A/B; arm and `system_v0.md` files were deleted 2026-08-29 after the null). Threepaired A/Bs all read null: glsl CLI (n=10/arm, Δ+0.003, within-arm σ 0.18), blendersingle-shot (8 pairs, paired Δ−0.027), blender CLI on 3.6-flash (10/10 pairs, pairedΔ−0.036, 4W/2T/4L, paired σ 0.403 — per-brief swings up to ±0.9 dwarf any promptdiff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.mdindex d6dcdf65..201b8752 100644--- a/harness/docs/INSTALL.md+++ b/harness/docs/INSTALL.md@@ -26,10 +26,10 @@ Once installed, read `docs/RUNBOOK.md` (how to run), `docs/ARCHITECTURE.md`git clone <repo> 3dcodeverse && cd 3dcodeversepython3 -m venv .venv && source .venv/bin/activate # see §3 — a distro python3 is# PEP 668 and pip will refuse it-bash harness/scripts/setup.sh # python + node deps + chrome + doctor+bash harness/setup.sh # python + node deps + chrome + doctor```-`scripts/setup.sh` is idempotent — it checks the interpreter versions, runs+`setup.sh` is idempotent — it checks the interpreter versions, runs`pip install -e 'harness[all,dev]'`, runs `npm ci` in `runtime_js/` **only when thelockfile actually moved**, makes sure puppeteer's Chrome is downloaded, andfinishes by printing `3dcodeverse doctor`. Useful flags:@@ -61,13 +61,13 @@ workflow, so the offline suite and `ruff` are run locally before every push (see| component | version | how it is enforced | notes ||---|---|---|---|-| **python** | **3.13** | `requires-python = ">=3.13"`; ruff `target-version = "py313"`; `PY_FLOOR` in `tests/core/test_portability.py`; `MIN_PY_MINOR` in `scripts/setup.sh` | the four places are pinned together by the portability test |+| **python** | **3.13** | `requires-python = ">=3.13"`; ruff `target-version = "py313"`; `PY_FLOOR` in `tests/core/test_portability.py`; `MIN_PY_MINOR` in `setup.sh` | the four places are pinned together by the portability test || **node** | **20.6.0+** (developed on 24 LTS) | `runtime_js/package.json` `engines.node`; `codeverse.spatial.node.NODE_MIN` fails every node workload with an actionable message | 20.6 is the `--import` module-hook floor || **Blender** | 4.2+ (developed on 5.0.1) | runtime probe only (`Settings.resolve_blender()`) | `blender` / `urdf_blender` are the only users || **OS** | Linux x86_64 (WSL2 Ubuntu here) | — | macOS should work (nothing is Linux-specific except `resource.setrlimit` guards) but is not tested |-The offline suite on this box, 2026-08-29: **2615 passed of the 2627 selected** (12 skipped are-data-dependent, 28 deselected are `live`).+The offline suite on this box, 2026-08-29: **1928 passed of the 1928 selected**+(25 deselected are `live`).Moving to another Python later is the same four-line change (`requires-python`, ruff`target-version`, `PY_FLOOR`, `MIN_PY_MINOR`).@@ -77,11 +77,10 @@ Moving to another Python later is the same four-line change (`requires-python`,| what | required? | verified here | how it degrades without it ||---|---|---|---|| **Python 3.13** | yes | 3.13.9 (`/home/yipeng/miniconda3/bin/python`) | nothing runs; `requires-python = ">=3.13"` (§2.1) |-| **pip + venv** | yes | pip 25.3, `python -m venv` | `scripts/setup.sh` cannot install the package. A stock Debian/Ubuntu `/usr/bin/python3` ships **without** pip and is PEP 668 `EXTERNALLY-MANAGED`, so `pip install -e harness` refuses even once pip is present: `sudo apt install python3-venv python3-pip`, then use a virtualenv |+| **pip + venv** | yes | pip 25.3, `python -m venv` | `setup.sh` cannot install the package. A stock Debian/Ubuntu `/usr/bin/python3` ships **without** pip and is PEP 668 `EXTERNALLY-MANAGED`, so `pip install -e harness` refuses even once pip is present: `sudo apt install python3-venv python3-pip`, then use a virtualenv || **git** | yes | 2.53.0 | run workspaces are git repos (one commit per round); `Workspace.create()` and the flywheel trajectory/pair miners fail || **node ≥ 20.6** | yes, except for the `graphics` track | v24.14.0 (npm 11.9.0) | the `threejs` / `scene_threejs` languages disappear **and no object renders happen at all**: `spatial/render.py` renders *every* GLB (Blender-built and CadQuery-built included) with three.js in headless Chrome. Only `graphics` (moderngl) is node-free || **Blender 4.2+ / 5.x** | optional | 5.0.1 (`~/.local/bin/blender-5.0`) | `blender` and `urdf_blender` languages unavailable → the `static_object` default language and the whole `articulated_object` track cannot build (`BlenderNotFoundError`); scenes lose planner-chosen bpy GLB assets |-| **ffmpeg** | optional | **not installed** | `render_turntable` silently writes an animated **GIF** via PIL instead of `.mp4` (`spatial/turntable.py`); nothing else changes || **EGL-capable GPU stack** | optional | ANGLE / D3D12 / RTX 5090 Laptop | headless Chrome falls back to **SwiftShader** and moderngl to **llvmpipe** — everything still renders, just several times slower; no correctness change || C toolchain | usually no | — | only if pip has to build a wheel from source (`python-fcl`, `manifold3d` ship wheels for cp310–cp313 x86_64) |@@ -105,7 +104,7 @@ import package `codeverse`, CLIs `3dcodeverse` and `3dcv`). See the repoUse a virtualenv (or a conda env — this box installs into a conda base env). It isonly optional when your interpreter already owns its site-packages: a distro`/usr/bin/python3` is PEP 668 `EXTERNALLY-MANAGED` and pip will refuse to install into-it. `scripts/setup.sh` checks for pip and for that marker up front and tells you which+it. `setup.sh` checks for pip and for that marker up front and tells you whichof the two you hit.```bash@@ -210,7 +209,7 @@ You need to re-run it when:* you pulled a change to `runtime_js/package.json` / `package-lock.json`, or* `3dcodeverse doctor` reports `three` or `puppeteer` FAIL.-`scripts/setup.sh` automates exactly that test: it compares the mtime of+`setup.sh` automates exactly that test: it compares the mtime of`package-lock.json` against `node_modules/.package-lock.json` and skips thereinstall when nothing moved (`--force-npm` overrides).@@ -408,7 +407,6 @@ runs_dir: /data/runscache_dir: /data/cache/codeversebinaries:blender: /home/yipeng/.local/bin/blender-5.0- ffmpeg: ffmpegrender:gpu: auto # auto | on | offwidth: 768@@ -465,7 +463,6 @@ Real output on this box (exit code 0; any FAIL row makes it exit 1):│ codex │ OK │ codex-cli 0.149.0 ││ agy │ OK │ 1.1.19 ││ git │ OK │ git version 2.53.0 │-│ ffmpeg │ WARN │ not found (turntable mp4 disabled) ││ mcp │ OK │ mcp + codeverse.spatial.mcp_server importable │└───────────────┴────────┴─────────────────────────────────────────────────────┘```@@ -497,7 +494,6 @@ that the keys work end to end):| `anthropic key` / `openai key` | WARN | not set | expected unless you use `anthropic:*` / `openai:*`; export the key to clear it || `gemini-cli` / `claude` / `codex` / `agy` | WARN | CLI not on `PATH` | optional (§8.2); only that `--generator` is unavailable || `git` | FAIL | git missing | install git — run workspaces are git repos |-| `ffmpeg` | WARN | not found | optional; turntables become GIFs. `sudo apt-get install ffmpeg` (or `conda install -c conda-forge ffmpeg`) || `mcp` | WARN | `mcp` package or the server module missing | `pip install -e 'harness[mcp]'`; only affects the agentic CLI backends || `gemini live call` (`--live`) | FAIL | key rejected / no network | check the key value and outbound access; a `503 … high demand` is transient, not an install problem || `gemini quota` | OK | always informational | the per-key RPM/TPM the pool schedules against x the number of keys (`Settings.rate`, docs/COST.md Part III); tune with `CV3D_RATE__TPM_PER_KEY` / `CV3D_RATE__MAX_IN_FLIGHT` |@@ -600,6 +596,5 @@ those by hand (`npm rm -g @google/gemini-cli @anthropic-ai/claude-code @openai/c| Chrome (puppeteer) | 148.0.7778.97 (+ headless-shell) | `~/.cache/puppeteer` || Blender | 5.0.1 (2025-12-16) | `~/.local/bin/blender-5.0` → `~/3dcodeverse_data/tools/blender-5.0.1-linux-x64` || git | 2.53.0 | `/usr/bin/git` |-| ffmpeg | not installed | — || gemini-cli / claude / codex / agy | 0.53.0 / 2.1.241 / 0.149.0 / 1.1.19 | npm global / `~/.local/bin` || GPU (Chrome WebGL) | ANGLE · D3D12 · NVIDIA GeForce RTX 5090 Laptop GPU · OpenGL ES 3.1 | via `--use-angle=gl-egl` + Mesa d3d12 |diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 177d4271..aa3d4e21 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -2,7 +2,8 @@This file lists the signatures other packages may rely on. Types live in`codeverse/contracts/`; protocols in `models/base.py`, `agents/base.py`,-`languages/base.py`, `spatial/registry.py`, `judges/base.py`, `tracks/__init__.py`.+`languages/base.py`, `spatial/registry.py`, `tracks/__init__.py` (judges are+duck-typed `.judge(JudgeInput) -> Judgment`; `judges/base.py` defines no protocol).Where the build deviated from the original plan the deviation is called out as**Δ** — see `docs/DECISIONS.md` for the why. When in doubt the code wins; thisfile was reconciled against it on 2026-08-23 (waves 2–3 + fix batch 1).@@ -17,8 +18,10 @@ file was reconciled against it on 2026-08-23 (waves 2–3 + fix batch 1).inside `tracks/generation.py` (`is_single_shot`, `single_shot_model_id`); neverregistered in `agents/`. `Spec.backends.generator` accepts any of the three.* Image models: `models/gemini.py::GeminiImageModel` (default- `gemini-3.1-flash-image`, fallback `gemini-2.5-flash-image`) behind the- `ImageModel` protocol (`generate`, `generate_with_usage` → `(images, Usage)`).+ `gemini-3.1-flash-image`, fallback `gemini-2.5-flash-image`); the one entry point+ is `generate_with_usage(prompt, *, size=1024, n=1, seed=None, reference_images=(),+ max_wait_s=None) -> (images, Usage)`, priced per GENERATED image via+ `pricing.per_image_usd(size=<generated px>)` (no `ImageModel` protocol, no `generate`).## core (contracts · config · proc)@@ -30,7 +33,8 @@ GateFinding.as_line(with_gate=False, with_severity=False, with_target=False, wit# "GATE <gate>: [<sev>] <message> [<target>] FIX: <hint>" — flags opt in; no leading "- "RenderView.judge: bool | None # stamped True/False at render time; None = legacy round (fall back to select_judge_views)RenderSet.out_dir: str # directory the views (+ views.json/metrics.json) were written to ("" on old rounds)-from codeverse.config import get_settings+from codeverse.config import get_settings, env_flag # env_flag(env, fallback) -> bool: on/off/1/0/true/false/yes/no;+ # unset/empty -> fallback; garbage -> warning + fallback (Settings value), never a silent switchget_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@@ -63,9 +67,15 @@ from codeverse.models.retry import KeyPool, KeyPoolExhaustedKeyPool(keys, *, rpm_per_key=900, tpm_per_key=None, cooldown_s=30, dead_cooldown_s=3600)pool.acquire(*, tokens_hint=0, exclude=None, timeout_s=120) -> key # raises immediately when every key is dead/cooling past the deadlinepool.try_acquire(*, tokens_hint=0, exclude=None) -> key | None # never waits (a hedged retry's extra key); holds a slot like acquire-pool.report(key, "ok"|"429"|"5xx"|"error"|"dead", *, tokens=0, retry_after_s=None) # Δ "dead": health 0, benched dead_cooldown_s, re-probed after+pool.report(key, "ok"|"429"|"5xx"|"error"|"dead"|"skip", *, tokens=0, retry_after_s=None) # Δ "dead": health 0, benched dead_cooldown_s,+ # re-probed after; "skip" (a content failure the key did not cause) reconciles tokens only — health and counters untouched+from codeverse.models.retry import with_retries, rotate_with_retries, RETRY_DEADLINE_S+with_retries(fn, *, is_retryable, attempts=6, base_delay=1.0, max_delay=3.0, max_total_s=None, ...) # max_total_s =+ # ChatRequest.max_wait_s clipped to RETRY_DEADLINE_S on every provider; stops before a backoff would cross it, stamps ModelError.attemptsfrom codeverse.models.pricing import estimate_cost # (provider, model, usage) -> usd (unknown model -> 0.0 + one warning)from codeverse.models.schema_utils import to_gemini_schema, to_openai_strict_schema, to_anthropic_schema, parse_json_lenient+from codeverse.models.schema_utils import ask_structured # (model, Schema, *, system, text, images=(), temperature, label)+ # -> (obj | None, Usage, err): one schema-bound call; call failure and parse failure are the same `err` family```Backends: `GeminiModel(model, *, keys=None, pool=None, ...)` (one shared KeyPool perkey list), `AnthropicModel(model, *, json_mode="tool"|"output_config")`,@@ -98,20 +108,22 @@ record_call(usage, *, run="", round=None, stage=None, role=None, label="", backeoutcome="ok", latency_ms=None, n_calls=1, source="live", ledger=None, reprice=False) -> CallCost# Δ everything left out is resolved from the ambient context + the call label (cost.context);# unknown model -> $0 and price_source="unknown" (flagged, never silently dropped); never raises.-from codeverse.cost.instrument import (run_ledger, metered_chat_model, metered_agent,- per_call_metering, meters_own_calls, IN_PROCESS_AGENT_KINDS)+from codeverse.cost.instrument import (run_ledger, metered_chat_model, metered_agent, meters_own_calls,+ MeteredAgent, MeteredChatModel, metering_enabled)with run_ledger(ws.root, run=slug): # binds the run, points record_call at <run>/telemetry/cost.jsonl... # (+ a <run>/cost_ledger.jsonl symlink for the run-layout alias)# NESTS (restores the outer ledger + run binding on exit) and is context-local first, so- # bench.run_bench / compare_backends can hold one ledger per prompt across N threads+ # bench.run_bench / compare_backends can hold one ledger per prompt across N threads.+ # BaseTrack.run opens `run_ledger(ws.root, run=ws.root.name)` ITSELF, so a track run started+ # outside the CLI/bench still meters; the CLI/bench ledger for the same run dir is the same file.# models.get_chat_model returns a MeteredChatModel → ONE row per ChatModel.generate- # agents.get_coding_agent returns a MeteredAgent → ambient round/stage for the session, the- # profile's turn cap (only ever LOWERS job.max_turns), and — iff NOT meters_own_calls(agent),- # a declaration no shipped backend makes — one session row.+ # agents.get_coding_agent returns a MeteredAgent (registry wrap, from the first call) → ambient+ # round/stage for the session and — iff NOT meters_own_calls(agent), a declaration no shipped+ # backend makes — one source='session' row (n_calls, latency, outcome, AgentResult.turns).+ # These two are the ONLY ledger writers; BudgetGuard writes no row.# The rule is the BACKEND, never "did a row get written while it ran": a CLI session with one# in-process tool call used to be dropped entirely, an in-process session whose turns ran in# another thread used to be counted twice. A backend may declare `meters_own_calls`.-per_call_metering() -> bool # aggregate writers (BudgetGuard) skip their row while Truefrom codeverse.cost.context import CallContext, call_context, bind_run, context_from_label, SELF_DESCRIBING# precedence: explicit > a label naming a job of its OWN (SELF_DESCRIBING = plan/judge/pairwise/# texture/caption) > ambient (call_context) > the rest of the label > nothing. A judge or a@@ -145,24 +157,27 @@ reconstructed, so all 61 recorded runs keep auditing.```pythonfrom codeverse.agents import get_coding_agent # (agent_id) -> CodingAgent .run(job) .available() .id .kind .modelfrom codeverse.agents.materialize import materialize_workspace, Materialized, codex_mcp_overrides-materialize_workspace(ws, *, agent_kind, contract_md, cookbook_rel, spatial_tools, mcp_command) -> Materialized+materialize_workspace(ws, *, agent_kind, contract_md, cookbook_rel, spatial_tools, mcp_command=None) -> Materialized+# mcp_command defaults to cli_common.default_mcp_command(ws) = [sys.executable, -m codeverse.spatial.mcp_server --workspace …]+# (None/[] = the default — no ValueError); tracks/common.Services.materialize takes no mcp_command# writes AGENTS.md + GEMINI.md + CLAUDE.md (same body), ws/.3dcv/cookbook.md (Δ copied in: gemini-cli cannot read# outside the workspace), .geminiignore/.aiexclude, and MCP wiring:# gemini-cli → ws/.gemini/settings.json only gets context.fileFiltering.respectGitIgnore=false; the 3dcv server# and mcp.allowed live in the per-session system settings (Δ that file is agent-writable — audit 2026-08-27)-# claude-code → trajectories/<label>_rNN/mcp.json codex → Materialized.codex_overrides:+# claude-code → trajectories/<label>_rNN/mcp.json codex → codex_mcp_overrides(mcp_command) built PER SESSION:# -c mcp_servers.3dcv.command=… -c mcp_servers.3dcv.args=[…] -c mcp_servers.3dcv.default_tools_approval_mode="approve"# (Δ without the approval mode every MCP tool call is elicited and auto-cancelled)# agy → no per-workspace MCP; body documents `3dcv tools <name> --json … --workspace .` as the fallbackres = agent.run(AgentJob(workspace=..., prompt=..., label="baseline", timeout_s=1800, max_turns=60,- spatial_tools=True, write_roots=["src","public"], extra={...}))+ spatial_tools=True, write_roots=["src","public"])) # typed kwargs only: no extra=, no model=res.ok, res.exit_reason # completed | timeout | error | budget | model_substituted+res.turns # claude-code num_turns · codex turn.completed count · agy num_turns · gemini-cli 0 (not on the wire)res.files_changed (git-derived, attributed per session), res.usage, res.transcript_path, res.tool_calls, res.errors````AgentJob` carries typed job context: `round`, `kind`, `language`, `track`,`mcp_command` (override), `files_hint` (workspace-relative files/dirs the task is-expected to touch — used to attribute `files_changed` between concurrent sessions in-one workspace; harness-owned paths and sibling sessions' hinted files are dropped),+expected to touch — used to attribute `files_changed`; harness-owned paths are dropped;+sessions on one workspace are serialised, so there is no sibling filter),`edit_only` / `always_writable` (a scoped refine may overwrite only its hinted files +the entry file), `read_only: list[str]` (harness-owned files INSIDE the write roots thesession may read but never write — `contracts.common.HARNESS_OWNED_SRC[language]`, i.e.@@ -191,11 +206,13 @@ rt.language; rt.entry_globsrt.lint(ws) -> GateReport # gate = "lint:<language>"rt.build(ws, *, timeout_s=None, **per_runtime) -> BuildResult # Δ BuildResult.error_file is WORKSPACE-relative forrt.skeleton(ws, plan) -> list[Path] # every runtime ("src/model.py", "src/parts/leg.py", "src/helpers.py")-rt.contract_doc() -> str ; rt.cookbook_path() -> Path+rt.contract_doc() -> str # cookbook path: tracks/common.cookbook_rel_for (no runtime hook)+BuildResult.error_type spellings (languages/_common.py): MISSING_ENTRY = "MissingEntryFile" (every runtime, threejs'+ export_glb.mjs included) · BUILD_TIMEOUT = "BuildTimeout" (compose_build_result, threejs, urdf)```| runtime | entry_globs | notes / artifacts ||---|---|---|-| `BlenderRuntime` | `src/model.py`, `src/parts/*.py` | **Δ multi-file**: `file_for_part(name) -> "src/parts/<snake>.py"` (`def build_<snake>()`), `file_for_target(target) -> list[str]`; lint = `layout.lint_workspace` over every src/*.py; skeleton writes model.py + per-part files; object.glb/stl, build.json, census.json |+| `BlenderRuntime` | `src/model.py`, `src/parts/*.py` | **Δ multi-file**: `file_for_part(name) -> "src/parts/<snake>.py"` (`def build_<snake>()`); lint = `layout.lint_workspace` over every src/*.py; skeleton writes model.py + per-part files; object.glb/stl, build.json, census.json || `CadQueryRuntime` | `src/model.py` | trailing selector on the stack → parent solid exported + warning (ExportError when no solid exists); helper-module errors map to `src/<file>.py:line`; object.glb/stl/step || `ThreeJsRuntime` | `src/object.js`, `src/parts/*.js` | **Δ export as authored** (`--normalise` opt-in, never passed by the runtime; census `placement_offset`/`normalised_offset`); InstancedMesh baked to `<Name>_<i>` meshes (`instanced_meshes_baked`); exported `selfcheck(THREE, root)` is called (throw → SelfCheckError); NaN geometry errors name mesh/part → routed to `src/parts/<snake>.js` || `UrdfBlenderRuntime` | `src/model.py`, `src/robot.urdf` | object.glb (Y-up, node=link, joint extras), meshes/<link>.glb (raw Z-up link frames); link name `world` is reserved (lint ERROR + UrdfError); robot GLB root gets `__root` suffix on name clash |@@ -226,7 +243,8 @@ are the pure helpers `3dcv doctor` reuses for its `node` row.`build_last.json`/`build.json` says the last build failed — tools never measure ortexture a stale GLB; missing/unreadable status stays permissive (hand-placed GLBs).```python-from codeverse.spatial.render import render_glb, render_turntable+from codeverse.spatial.render import render_glb+from codeverse.contracts.artifacts import RENDER_MODES # ('shaded','wire','normals','silhouette','clay') — THE mode tuple (no 'depth')render_glb(glb, out_dir, *, views=None, mode="shaded|wire|normals|silhouette|clay", width=768, height=768,isolate=None, explode=0.0, sheet=True, background=..., anim_time=None, shadow=True, gpu=None,timeout_s=None, use_cache=True) -> RenderSet@@ -243,7 +261,7 @@ frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; dafrom codeverse.spatial.measure import measure_glb # link-hierarchy rule: metadata["links"] → each link is its own part# Δ Measurement.extra["complexity"] = ComplexityVector.model_dump() (additive, best-effort, never raises)from codeverse.spatial.complexity import (ComplexityVector, COMPLEXITY_WEIGHTS, COMPLEXITY_VERSION,- complexity_of_glb, complexity_of_parts, complexity_summary_line, band_of)+ complexity_of_glb, complexity_of_parts, band_of)complexity_of_glb(glb) -> ComplexityVector # part_count, assembly_depth, tri_count, materials, silhouette,# feature_density, symmetry_groups, hollowness, + index 0-1 (documented weights) and band# (trivial|simple|moderate|complex|intricate). Deterministic, no VLM/render. docs/COMPLEXITY.md@@ -255,8 +273,11 @@ check_placement(ws, *, indoor=None, force_probe=False) -> GateReport # gate "s# unsupported | interpenetration | summary | probe_failed; target "Zone/Asset" (routes to src/zones/<zone>.js);# messages carry the scene_v1 floating_part cap words; reads artifacts/census.json["placement"] (host_placement.mjs)placement_gate_safe(census, *, plan=None) -> GateReport | None # round gate: None without a table, WARN on failure, never raises+from codeverse.spatial.scene_placement import setting_text # (plan: dict | model) -> the indoor/outdoor setting linefrom codeverse.spatial.silhouette import compare_silhouettefrom codeverse.spatial.joints import load_urdf, fk, sweep_collisions, urdf_to_glb, render_poses # RESERVED_LINK_NAMES={'world'}+from codeverse.spatial.joints_collide import components # (names, edges) -> list[set[str]]: THE union-find (connectivity + sweep)+# the joint_sweep TOOL body lives in spatial/tools.py (no joint_sweep_observation helper; render_poses takes no renderer=)# joints_collide.py: deterministic penetration (oriented islands + fixed-direction parity ray test; python-fcl is a# core dependency, the trimesh fallback is deterministic too)from codeverse.spatial.gl_render import GlHost, GlResult, GlHostError, write_contact_sheet, write_gif@@ -279,7 +300,7 @@ from codeverse.judges.vlm_judge import VlmJudgeVlmJudge(rubric="static_object_v1", model_id=None (settings.default_judge = gemini-3.1-pro-preview), n_samples=1,temperature=0.2, *, thinking="low", max_attempts=3, max_montages=3, detail_crops=2, max_px=1024, sample_budget_s=240,chat_model=None, cache_dir=None, label="judge") # Δ max_images is GONE → montage budget-VlmJudge.judge(inp, *, geometry_views: RenderSet | None = None) -> Judgment # also reads inp.geometry_views+VlmJudge.judge(inp) -> Judgment # clay/normals views travel ONLY as JudgeInput.geometry_views (no kwarg)from codeverse.judges.base import JudgeInput # (spec, renders, measurement=None, gates=[], acceptance=[], plan_summary="",# round_index=0, previous=None, extra_context="", geometry_views=None)from codeverse.judges.prompt_builder import plan_montages, render_montage, Montage # ≤3 2×2 montages (shaded/geometry/poses) + ≤2 detail@@ -309,7 +330,8 @@ must-acceptance`; gate authors set `GateFinding.data["kind"]` so caps match precfrom codeverse.tracks import get_trackrec = get_track(spec.track, **options).run(spec, ws, resume=False) -> RunRecord # Δ kwargs forwarded to the constructor:# services=, judge=, agent=, model=, runtime=, policy=RoundPolicy, settings=, planner_model=, n_candidates=-# (CLI --candidates > run_state.extra > settings.default_candidates); StaticObject | Articulated | Scene | Graphics+# (CLI --candidates > spec.options.candidates > settings.default_candidates); StaticObject | Articulated | Scene | Graphics+TrackPipeline.run(spec, ws, *, resume=False, force=False) -> RunRecordfrom codeverse.orchestrator import RoundPolicy, StopPolicy, StopDecision, BestSelector, judge_sigma, \best_score, last_gain, REWRITE_KIND, build_refine_instructions, compact_instructionsRoundPolicy(max_rounds=4, plateau_window=2, min_delta=0.02, target=0.8, judge_on_gate_errors=True, max_refine_tasks=6,@@ -317,29 +339,36 @@ RoundPolicy(max_rounds=4, plateau_window=2, min_delta=0.02, target=0.8, judge_onpairwise_min_confidence=0.6, judge_samples=1,judge_model="", regression_sigma=1.0, regression_allow_switch=True, # money stops (docs/COST.md §5)marginal_sigma=1.5, marginal_from_round=3, # r03+ must beat 1.5σ- agent_max_turns=0, agent_wrapup_turns=6, # 0 = UNCAPPED: a 28-turn cap was A/B'd- # and rejected (+$0.02, −0.21 score, docs/COST.md §17); wrapup applies to a cap a caller sets- detail_rounds=0, detail_min_score=0.45, detail_bbox_tol_m=0.005 # surface-detail round;- # 0 here, raised to 1 by lifecycle.detail_round_budget for tracks with supports_detail_round- # ($CV3D_DETAIL_ROUNDS overrides both — the A/B switch)- ).with_candidates(n).with_judge(spec.backends.judge)+ agent_max_turns=0, agent_wrapup_turns=6, # 0 = the backend's own AgentJob.max_turns (claude-code 60+ # +6 wrap-up; gemini-cli/codex/agy no turn cap); a 28-turn cap was A/B'd and rejected (+$0.02, −0.21+ # score, docs/COST.md §17); wrapup applies to a cap a caller sets+ detail_rounds=None, detail_min_score=0.45, detail_bbox_tol_m=0.005 # surface-detail round, tri-state:+ # None = the track default (lifecycle.DEFAULT_DETAIL_ROUNDS=1 when supports_detail_round, else 0),+ # 0 = off, N = N; $CV3D_DETAIL_ROUNDS overrides all (the A/B switch). Injected policies keep it.+ ) # lifecycle.build_context binds n_candidates + judge_model with ONE dataclasses.replace;+ # RoundPolicy.target is ALWAYS overridden by the rubric pass threshold in BaseTrack.after_planpolicy.sigma / .regression_delta / .marginal_delta # judge_sigma() reads cost.routing.JUDGE_NOISE — THE σ tableStopPolicy(policy).evaluate(history, budget_ok=True) -> StopDecision(reason, strategy="same"|"switch"|"detail", detail)- # .decide(...) -> StopReason is unchanged; strategy "switch" = ONE whole-artifact rewrite round (kind REWRITE_KIND),+ # (.reason is the StopReason); strategy "switch" = ONE whole-artifact rewrite round (kind REWRITE_KIND),# "detail" = ONE surface-detail round (kind DETAIL_KIND) — a plateau/diminishing stop is converted into it# only when detail_blocked(history, policy) == "" (clean gates, built, judged, within σ of best, budget left)-from codeverse.orchestrator import DETAIL_KIND, kind_for_strategy, detail_blocked # THE strategy → kind map+from codeverse.orchestrator import DETAIL_KIND, KIND_FOR_STRATEGY, detail_blocked # THE strategy → kind dictfrom codeverse.orchestrator import BudgetGuard, usage_delta-BudgetGuard(budget, *, soft_fraction=1.0, run="", ledger=None)- .spend(usage, *, stage="other", role=None, label="", round_index=None, outcome="ok", enforce=True)- # THE door every dollar goes through: accumulate → bucket by stage/round → one priced ledger row- # (skipped when cost.instrument.per_call_metering() already writes them) → enforce the ceilings.- # charge(...) = spend(enforce=True); add(...) = spend(enforce=False) — "not enforced" never means "not seen".- .by_stage / .by_round / .round_costs(i) / .stage_summary() / .mark() # what a round burned, live+BudgetGuard(budget, start_time=None, *, soft_fraction=1.0) # no run= / ledger=+ .charge(usage, *, stage="other", role=None, label="", round_index=None, outcome="ok", enforce=True)+ # THE door every dollar goes through: accumulate → bucket by stage/round → enforce the ceilings.+ # It writes NO ledger row: cost.instrument.MeteredAgent (one source='session' row per CLI session) and+ # MeteredChatModel (one row per call) are the only writers of telemetry/cost.jsonl.+ # add(...) = charge(enforce=False) — "not enforced" never means "not seen".+ .by_stage / .by_round[i] / .stage_summary() / .mark() # what a round burned, livefrom codeverse.tracks.candidates import CandidateRecord, rank_candidates, decide_best # pure decision logic-from codeverse.tracks.candidates import run_best_of_n, choose_best_round # N parallel baselines in <ws>/_cand/c<k>-# (quick 4-view judge, crashed candidate retried once; selection by build_ok → quick score → fewer gate errors, pairwise-# within margin); winner copied back, normal r00 pipeline follows; rounds/candidates.json + record.extra["candidates"]+from codeverse.tracks.candidates import run_best_of_n, choose_best_round, quick_render # N parallel baselines in <ws>/_cand/c<k>+# each candidate IS steps._run_round(kind="candidate") in its sub-workspace: render=quick_render(ctx, round_index, build,+# measurement, *, pipeline) (4 views + the articulated pose views), geometry_views=False, its own events.jsonl and a+# one-sample judge → _cand/c<k>/judge/r00.json (a degraded verdict stays score None); crashed candidate retried once;+# selection by build_ok → quick score → fewer gate errors, pairwise within margin (booked stage=judge label="pairwise");+# winner copied back, normal r00 pipeline follows; rounds/candidates.json IS record.extra["candidates"] (n, selected,+# candidates[], pairwise)from codeverse.tracks.articulated_object import default_motion_checks, expected_direction # gate "motion_direction"from codeverse.tracks.static_object import silhouette_gate, reference_refine_tasks # gate "reference_silhouette" (IoU<0.6 → WARN + refine task)from codeverse.tracks.depth import depth_budget, DepthBudget, scope_groups, PartScope, interfaces_text, \@@ -358,7 +387,7 @@ from codeverse.tracks.prompting import base_prompt_context, reference_images, fifrom codeverse.tracks.prompting import select_cookbook_chapters, is_always_chapter# 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 codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY, RECIPES_REL+from codeverse.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'# 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@@ -367,7 +396,11 @@ from codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cook# {file, names, present, chapters, trimmed}. Never writes src/common.glsl — except the untouched skeleton,# which loses the helpers recipes.glsl now provides (trim_skeleton_common; recipes are pasted first).# GraphicsTrack.prepare() runs it after the skeleton and commits "recipes" when it wrote something.-from codeverse.tracks.common import RunContext, Services # common.py+from codeverse.tracks.common import RunContext, Services # common.py; RunContext.single_shot / .agent_kind+from codeverse.tracks.generation import write_files # (ws, files, *, allowed_roots, only=None, frozen=(), on_skip=None):+ # frozen = harness-owned paths a single-shot envelope may not rewrite (skipped with a reason, never an error)+from codeverse.agents.cli_common import find_json_object, default_mcp_command # THE one JSON-envelope finder behind+ # parse_gemini_json / parse_claude_json / parse_agy_json; default_mcp_command(ws, *, language, track, round_index)from codeverse.tracks.generation import generate, run_agent_task, parse_multifile, is_single_shotGenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases in ascending order# (tracks.steps.run_generation_tasks). Only user: the scoped baseline — phase 0 = one session per@@ -386,7 +419,9 @@ skip_judge_reason(ctx, *, gates, renders) -> str # "" = judge it. ONLY state# never bought at all: no judge / no renders / budget already exceeded / gate errors with# policy.judge_on_gate_errors=False. rejudge_round honours the last one too, so a policy skip is# never re-bought (docs/COST.md §17 — "no file change" and "build not repaired" were removed)-run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None) -> RoundRecord+run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None, render=None, geometry_views=True) -> RoundRecord+ # render: RenderFn | None swaps the pipeline's render (candidates pass quick_render); geometry_views=False skips+ # the clay/normals views# emits cost.round {stages{}, judge_usd, total_usd, agent_turns, wasted, waste_reason}; on ANY exception it# records what the round burned (rounds/aborted_rNN.json, ctx.extra["aborted_rounds"]) and re-raisesfrom codeverse.tracks.planner import plan, plan_model_for, ensure_acceptance # graphics uses tracks/graphics.plan_graphics@@ -419,7 +454,8 @@ from codeverse.texturing.plan import scene_texture_pack, texture_pack_prompt ### flywheel/ + cli/```python-from codeverse.flywheel.record import finalize_record, load_record, iter_runs, best_round_index+from codeverse.flywheel.record import finalize_record, load_record, iter_runs, best_round_index, best_round_record+from codeverse.gallery.index import hero_view # (ws, rec) -> (rel, label, n_views): the card image, rebased via wsfrom codeverse.flywheel.record import complexity_block, round_complexity # objective complexity of what shipped# finalize_record fills record.extra["complexity"] = the BEST round's vector + plan_parts /# parts_per_plan_part / by_round; every rounds_summary row gains "complexity" (the index or None)@@ -456,7 +492,7 @@ Event names: `run.start`, `stage.start/done`, `plan.done`, `workspace.materializ`texture.start/plan/generated/applied/gate/done`, `budget.exceeded`,`finalise.rebuild`, `stop`, `run.done` / `run.failed`.Cost events: **`cost.round`** (per round: `stages{stage → $}`, `judge_usd`, `total_usd`,-`agent_turns`, `score`, `previous_best`, `wasted`, `waste_reason` ∈ aborted | build_failed |+`agent_turns` (= AgentResult.turns), `score`, `previous_best`, `wasted`, `waste_reason` ∈ aborted | build_failed |unjudged | regression | zero_delta, `run_usd`) — emitted for aborted rounds too;`judge.skipped` (reason), `generate.turn_cap` (label, max_turns, turns, cost_usd),`strategy.switch` (regression → whole-artifact rewrite), `budget.overrun` (a post-loop@@ -464,6 +500,6 @@ texture pass crossed the ceiling; the loop is already finished, so not `budget.e`RunRecord` (record.json): spec, plan, workspace, status, rounds[RoundRecord],best_round, baseline_score, final_score, total_usage, environment,prompt_hashes{contract, cookbook, generate, refine}, error, extra{stop_reason,-rubric, budget, cost_by_stage, aborted_rounds?, rounds_summary, n_candidates?,-candidates?, texturing?, captions?}. `total_usage` is the BudgetGuard total whenever it+rubric, budget, cost_by_stage, aborted_rounds?, rounds_summary, candidates? (the+rounds/candidates.json payload), texturing?, captions?}. `total_usage` is the BudgetGuard total whenever itexceeds the sum of the rounds (aborted rounds, retried sessions, texture pass).diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex d7494aa9..a13d96fa 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -10,7 +10,7 @@ are relative to `/home/yipeng/3dcodeverse/harness` unless absolute. The CLI is```bashpip install -e /home/yipeng/3dcodeverse/harness # once; entry points 3dcodeverse and 3dcvcd /home/yipeng/3dcodeverse/harness/runtime_js && npm install # [email protected], puppeteer (chrome cached)-3dcv doctor # python deps (incl. python-fcl, moderngl), blender, node/three/puppeteer, chrome WebGL, keys, CLIs, git, ffmpeg, mcp+3dcv doctor # python deps (incl. python-fcl, moderngl), blender, node/three/puppeteer, chrome WebGL, keys, CLIs, git, mcp3dcv doctor --live # + one tiny Gemini call ("pong", ~$0.00001)python -m pytest tests -q # offline suite; live tests are opt-in (blender/node/GL run when the binaries exist)python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset@@ -240,12 +240,12 @@ model, produced the zero — check `cell.json`'s `error`).* **New language**: enum in `contracts/common.py::Language` (+ `TRACK_LANGUAGES`,`ENTRY_FILE`, `LANGUAGE_LABEL`), frame in `conventions.LANGUAGE_FRAME`;- `languages/<lang>/{runtime.py, lint.py, skeleton.py, CONTRACT.md, wrappers/}`- implementing `LanguageRuntime`; branch in `languages/base.py::get_runtime`;+ `languages/<lang>/{__init__.py, wrappers/}` (one merged module per language;+ the contract text is `prompts/<lang>/contract.md`) implementing `LanguageRuntime`; branch in `languages/base.py::get_runtime`;`prompts/<lang>/contract.md` + `cookbook.md` (every snippet must run —`tests/prompts` executes them); part→file mapping via `runtime.file_for_part`- (blender and threejs have it; `tracks/prompting.file_for_target_factory` picks- it up).+ (blender has it; `tracks/prompting.file_for_target_factory` picks it up and maps+ every whole-object target to `[entry]` — no runtime `file_for_target` hook).* **New spatial tool**: pydantic args + `@tool("name", Args, "…", tracks=(…),languages=(…), cost_hint=…)` in `spatial/tools*.py` (imported from`spatial/tools.py`); available to tracks, MCP and prompt cards at once.@@ -258,7 +258,10 @@ model, produced the zero — check `cell.json`'s `error`).* **New backend**: ChatModel → `models/<provider>.py` + registry + prices;CodingAgent → `agents/<kind>.py` using `cli_common` + registry + `materialize.py`.* **New track**: subclass `tracks/lifecycle.py::BaseTrack` (hooks: `make_pipeline`,- `prepare`, `baseline_tasks`, `refine_tasks`, `round_files_hint`), a `RoundPipeline`,+ `prepare`, `baseline_tasks`, `refine_tasks`, `round_files_hint`; `system_prompt`+ defaults to `language_system_prompt(ctx.language, tools=not ctx.single_shot)` and+ `refine_file_for_target` to `file_for_target_factory(ctx)` — override only for+ role-specific prompts), a `RoundPipeline`,plan model in `contracts/plan.py`, `.j2` prompts, branch in `tracks/__init__.py`(`get_track` forwards `**options` to constructors). `tracks/graphics.py` is thetemplate for a track with its own planner and no GLB.diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.mdindex bed4b2e3..6f46dc1d 100644--- a/harness/docs/RUN_LAYOUT.md+++ b/harness/docs/RUN_LAYOUT.md@@ -50,12 +50,15 @@ symlink. Which side is physical was not a matter of taste:must be on the alias side, never on the side that gets written.* **`deliverable/`, `telemetry/settings.json` and `telemetry/cost.json` are realfiles.** They are *derived*: rebuilt from the run's own git history,- artifacts, trajectories and events every time the run is finalised or- migrated. `deliverable/` is self-contained so it can be zipped and handed to+ artifacts, trajectories and events every time the run is finalised, and on+ the fly by `3dcv show` / the exporters for a run that predates them — old+ runs are read as-is, never rewritten. `deliverable/` is self-contained so it can be zipped and handed tosomeone (the flywheel exporter only falls back to it when git cannot answer).`telemetry/usage.jsonl` is the one file that can be either: a real- reconstructed ledger, or a symlink to the run's live `cost_ledger.jsonl` when- it has one — same rule as everywhere else, one physical copy.+ reconstructed ledger, or a symlink to the run's live `telemetry/cost.jsonl`+ when it has one (the root `cost_ledger.jsonl` is itself a symlink alias; a+ real root file exists only in runs before 2026-08-23) — same rule as+ everywhere else, one physical copy.`.gitignore` inside the run ignores `deliverable/`, `telemetry/` and `evidence`(as well as `artifacts/`, `stages/`, `trajectories/`, …) so the derived buckets@@ -103,7 +106,8 @@ the packager produces no diff.* **`usage.jsonl`** — one priced row per model call, in the**`codeverse.cost` ledger format** (`CallCost`: tokens, unit prices, priceprovenance, stage, role, outcome). There is exactly one ledger in the- harness: when the run wrote a live one (`<run>/cost_ledger.jsonl`)+ harness: when the run wrote a live one (`<run>/telemetry/cost.jsonl`; the root+ `cost_ledger.jsonl` is a symlink alias, a real root file only in pre-2026-08-23 runs)`telemetry/usage.jsonl` is a symlink to it, otherwise`cost.reconstruct.reconstruct_run` rebuilds the rows from the trajectories,the recorded judge verdicts and the priced events. This bucket never@@ -145,20 +149,6 @@ For the money itself across many runs — waste, $ per passing artifact, priceprovenance — use the cost package's own command, `3dcv cost show <runs-dir>`.`3dcv show` is the single-run view; both read the same ledger rows.-## Migrating existing runs--```-3dcv migrate-runs runs/ --dry-run # report only, touches nothing-3dcv migrate-runs runs/ # in place, idempotent-3dcv migrate-runs runs/<slug> # a single run directory-```--The migration only **adds**: it creates the buckets and aliases, builds-`deliverable/` and `telemetry/`, and writes the two new record blocks. It never-moves or deletes evidence, never rewrites `src/`, never touches git history. A-second pass reports `up_to_date`. Runs without a `record.json` (interrupted-runs) get the layout only.-## Back-compatibility contract* Old runs load unchanged — `load_record`, `3dcv status`, `3dcv judge`,diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.mdindex 24d2fa04..bdf3a917 100644--- a/harness/docs/SKILLS.md+++ b/harness/docs/SKILLS.md@@ -98,7 +98,7 @@ not mean that.** Two independent causes, both reproduced:So a fourth signal was added: `materialize.write_control` puts one **never-routed,never-indexed** bundle beside the real ones. Nothing should ever open it. When it comesback opened, `SkillsUsage.control_read` is set, `probe_trustworthy` is false and-`deep_read_rate` returns **`None`** — not 100%, not 0. `3dcv skills report` excludes those+the session's deep-read rate is **`None`** — not 100%, not 0. `3dcv skills report` excludes thosesessions from the rate and prints how many it dropped.This is the difference between a metric and a number that would have read 100% forever.@@ -245,7 +245,9 @@ Two things this also says, and neither is comfortable:## 5. What the tests guarantee-`tests/skills/` — 712 tests: 650 that run in the default suite, 58 marked `slow` (they recompute from `bench/out` or build a wheel), 4 marked `live` (they drive a real CLI).+`tests/skills/` keeps the default checks hermetic. The two `slow`-marked cases+build a wheel (still selected by default; use `-m "not slow"` to omit them), and+the `live` cases drive a real CLI.| file | guarantees ||---|---|@@ -255,7 +257,6 @@ Two things this also says, and neither is comfortable:| `test_freshness.py` | every tool, gate kind, rubric criterion, constant, switch, sibling skill and cookbook section a bundle names still exists || `test_router.py` / `test_routing_property.py` | the four routing laws, by row and over the whole input space || `test_budget.py` | the index cost, re-measured against the shipped descriptions |-| `test_corpus.py` | evidence labels and corpus claims recomputed from `bench/out` || `test_telemetry.py` | the read probe, **including the control that catches git reading the tree** || `test_packaging.py` | **a built wheel contains all 14 `SKILL.md`, all 14 `references/`, all 9 `_claims`** || `test_live_discovery.py` | §7 — a real CLI actually finds and opens a bundle |@@ -546,8 +547,9 @@ so; the rest are live.reaching `skills_hook.attach_for_round`, which lived only in `steps.run_round`; and`baseline_tasks` returned `[]`, so round 0 listed four bundles to a session that did notexist. Measured at **0 opens / 30 listings**. The three stages now attach and record with- their own kind. `tests/skills/test_delivery_reaches_the_session.py` holds every- agent-driving module to the hook. **The scene bundles' read rate against working delivery+ their own kind. `tests/skills/test_delivery_reaches_the_session.py` runs a real+ two-zone-session scene and proves env/zone/compose attach exactly once, before generation,+ with matching telemetry. **The scene bundles' read rate against working deliveryis UNMEASURED — that is the next wave's first experiment.*** ~~**`api-agent` has no skill affordance.**~~ **FIXED earlier**, and re-measured here: with`read_skill` it opens **58%** of listed bundles (51/88) across sessions that are offereddiff --git a/harness/docs/SKILLS_LEDGER.md b/harness/docs/SKILLS_LEDGER.mdindex 05ac369b..ef05ea5d 100644--- a/harness/docs/SKILLS_LEDGER.md+++ b/harness/docs/SKILLS_LEDGER.md@@ -230,7 +230,7 @@ it lands these four rows stay `mixed`, not `measured`.intact; but any A/B straddling this commit compares two different metrics.`cv3d-scene-lighting` must be re-baselined against the new gate before it is paired.* **`shader_preflight` is not a gate at all.** It appears in **zero** `record.json` files- corpus-wide: `check_shaders` is an agent-invocable tool (`spatial/tools_scene.py`), never a+ corpus-wide: `check_shaders` is an agent-invocable tool (`spatial/tools.py`), never apipeline gate, so no round appends its report. The only evidence is 8 per-run`artifacts/shader_preflight.json` files, all clean. "Not instrumented" and "measured,always clean" must not print the same number — the readout now returns `None` when the