Official Codebase of 3DCodeVerse
Python
orchestrator: the round history lives once, in the journal — RunState stops caching it
gaoypenga561b64b513f
diff --git a/harness/codeverse3d/orchestrator.py b/harness/codeverse3d/orchestrator.pyindex 8b068619..b65f0db9 100644--- a/harness/codeverse3d/orchestrator.py+++ b/harness/codeverse3d/orchestrator.py@@ -46,15 +46,15 @@ class StageState(BaseModel):class RunState(BaseModel):- """Everything the orchestrator needs to resume a run. A state saved before 2026-09-22- also names a best round (``best_round`` / ``best_commit`` / ``best_score`` /- ``best_considered_through``): unknown keys, ignored — a resume goes on from the LAST round."""+ """Everything the orchestrator needs to resume a run — except the round history, which is+ the round journal's alone (``rounds/rNN.json`` + each round's commit; ``lifecycle.reconcile_resume``+ reads it). A state saved before 2026-09-22 also caches that journal (``completed_rounds`` /+ ``round_commits`` / ``current_round``) and names a best round (``best_round`` / ``best_commit`` /+ ``best_score`` / ``best_considered_through``): unknown keys, ignored — a resume goes on from the+ journal's LAST round."""status: RunStatus = RunStatus.PLANNINGstages: dict[str, StageState] = Field(default_factory=dict)- current_round: int = Field(default=0, description="index of the round in progress / next to run")- completed_rounds: list[int] = Field(default_factory=list)- round_commits: dict[int, str] = Field(default_factory=dict)materialized_for: str = Field(default="", description="agent kind the workspace was materialised for")stop_reason: str = ""error: str = ""@@ -85,13 +85,6 @@ class RunState(BaseModel):self.updated_at = datetime.now(UTC)ws.write_json(ws.state_path, self)- # ----------------------------------------------------------------- helpers- def mark_round_done(self, index: int, commit: str) -> None:- if index not in self.completed_rounds:- self.completed_rounds.append(index)- self.round_commits[index] = commit- self.current_round = index + 1-class StateCorrupt(RuntimeError):"""``run_state.json`` exists but does not validate — refuse to guess."""diff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.pyindex 3f0824dc..ced6406b 100644--- a/harness/codeverse3d/tracks/lifecycle.py+++ b/harness/codeverse3d/tracks/lifecycle.py@@ -292,11 +292,9 @@ class BaseTrack:# ------------------------------------------------------------------ resume reconciliationdef reconcile_resume(self, spec: Spec, ws: Workspace, events: EventLog, state: RunState,*, resume: bool, force: bool) -> list[RoundRecord]:- """Make ``run_state.json`` agree with the on-disk round journal before anything runs.-- The journal (``rounds/rNN.json`` + its git commit, written at the end of every- round) is the durable record; the state file is a cache of it that a crash can- leave stale — round persisted, ``mark_round_done`` never saved. On resume:+ """The round history a resume goes on from: the on-disk round journal (``rounds/rNN.json``+ + its git commit, written at the end of every round) — the one record of it; the state file+ keeps no copy that a crash could leave behind. On resume:1. **Spec identity.** ``state.extra["spec_fingerprint"]`` (hash of:func:`plan_stage_inputs`, stamped on first run) must match the spec we are@@ -306,9 +304,8 @@ class BaseTrack:to ``rounds/pre_force/`` — old rounds are never paired with a new spec/plan.2. **Journal integrity.** Trailing rounds whose commit git does not have aredropped (half-written journal), with a ``resume.dropped_rounds`` event.- 3. **Rebuild.** ``completed_rounds``/``round_commits`` come from the journal, and- the working tree goes back on the LAST round's commit when anything left it- elsewhere — a crash mid-round, or the finalise of a run recorded before+ 3. **The tree.** The working tree goes back on the LAST round's commit when anything+ left it elsewhere — a crash mid-round, or the finalise of a run recorded before2026-09-22, which restored its best round. The next round refines the roundbefore it, always.@@ -336,7 +333,6 @@ class BaseTrack:events.emit("resume.archived", dest=str(archived))journal = []state.stages.pop("plan", None) # the plan must be rebuilt from the edited spec- state.completed_rounds, state.round_commits, state.current_round = [], {}, 0state.extra["spec_fingerprint"] = fpkept: list[RoundRecord] = []dropped: list[int] = []@@ -349,19 +345,12 @@ class BaseTrack:events.emit("resume.dropped_rounds", rounds=dropped,reason="round journal names commits git does not have")journal = kept- journal_commits = {r.index: r.commit for r in journal}- stale = (state.completed_rounds != [r.index for r in journal]- or {int(k): v for k, v in state.round_commits.items()} != journal_commits)- if stale:- state.completed_rounds = [r.index for r in journal]- state.round_commits = dict(journal_commits)- state.current_round = len(journal)restored = bool(journal) and self._needs_restore(ws, journal[-1].commit)if restored:ws.restore(journal[-1].commit)ws.commit(f"resume from the last round r{journal[-1].index:02d}")state.save(ws)- events.emit("resume.reconciled", rounds=len(journal), dropped=dropped, state_was_stale=stale,+ events.emit("resume.reconciled", rounds=len(journal), dropped=dropped,restored_last_round=journal[-1].index if restored else None, spec_fingerprint=fp)return journal@@ -465,10 +454,10 @@ class BaseTrack:return [str(Path(p).relative_to(ctx.ws.root)) if Path(p).is_absolute() else str(p) for p in paths]inputs = {"plan": ctx.plan, "language": ctx.language.value}- if ctx.state.completed_rounds and not runner.is_done("skeleton", inputs):+ if not runner.is_done("skeleton", inputs) and (journal := load_round_journal(ctx.ws)):# stale skeleton hash on resume: rounds exist, so re-running the skeleton# writer would overwrite agent-authored src/ — never do that.- ctx.events.emit("skeleton.skipped", reason="rounds_exist", rounds=len(ctx.state.completed_rounds))+ ctx.events.emit("skeleton.skipped", reason="rounds_exist", rounds=len(journal))return []return runner.stage("skeleton", _do, inputs=inputs)@@ -536,7 +525,6 @@ class BaseTrack:# that is only because the judge never scored the round, say so.unjudged = last.judgment is None and last.build is not None and last.build.okreturn _stop(RunStatus.JUDGE_UNAVAILABLE if unjudged else RunStatus.NO_REFINE_TASKS)- ctx.state.current_round = indexctx.state.save(ctx.ws)try:if index == 0 and tasks and ctx.policy.n_candidates > 1:@@ -572,9 +560,6 @@ class BaseTrack:ctx.events.emit("round.no_change", round=index, detail=str(e)[:500])return _stop(RunStatus.NO_CHANGE)rounds.append(rec)- # a crash before this save leaves the state behind the journal, which- # reconcile_resume detects (stale) and repairs from the journal- ctx.state.mark_round_done(index, rec.commit)self._save_budget(ctx)def _salvage_baseline(self, ctx: RunContext, rounds: list[RoundRecord]) -> None:@@ -586,7 +571,7 @@ class BaseTrack:fraction of a generation session, so grant an explicit one-off grace anddeliver ONE no-generation round. Any failure here is swallowed: the run isalready stopping on budget."""- if rounds or ctx.state.completed_rounds or ctx.plan is None:+ if rounds or ctx.plan is None:return # nothing was built yet (the PLAN itself blew the budget) → nothing to salvagegrace_min = max(5.0, ctx.spec.budget.max_minutes * 0.15)ctx.budget.grant_grace(minutes=grace_min)@@ -604,7 +589,6 @@ class BaseTrack:ctx.events.emit("budget.salvage_failed", error=f"{type(e).__name__}: {e}")returnrounds.append(rec)- ctx.state.mark_round_done(0, rec.commit)self._save_budget(ctx)def _save_budget(self, ctx: RunContext) -> None:diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 28625049..a94dfa3c 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -302,7 +302,8 @@ runs/<slug>/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-layoutalias; runs before 2026-08-23 have the root file only)- run_state.json stages + rounds done; extra carries budget_snapshot and spec_fingerprint only+ run_state.json status + stages; extra carries budget_snapshot and spec_fingerprint only — the round+ history is rounds/rNN.json + each round's commit alone (no copy since 2026-09-22)artifacts/ object.glb object.stl|step robot.urdf meshes/ articulation.json build.json census.jsonmeasurement.json … — the LAST round's build; graphics: frames/fNN_tT.png frames_sheet.pngpreview.gif metrics.json; texturing (a pick's --texture): object_textured.glbdiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 56993b58..1fc8dc78 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -634,7 +634,8 @@ Event names: `run.start`, `stage.start/done`, `plan.done`, `workspace.materializ`round.start`, `generate.done`, `build.done`, `gates.done`, `judge.done`,`round.done`, `refine.planned`, `recipes.seeded` (graphics: names written this call, present on disk, chapters), `asset.judged`, `assets.done`,`zones.done`, `assemble.done`, `round.no_change`, `candidates.start`,-`candidate.start/done/failed/retry/selected`, `resume.reconciled` (…, `restored_last_round`),+`candidate.start/done/failed/retry/selected`, `resume.reconciled` (rounds, dropped, `restored_last_round`; Δ 2026-09-22 no+`state_was_stale`: run_state.json keeps no copy of the round journal to go stale),`texture.start/plan/generated/applied/gate/done`, `budget.exceeded`,`finalise.rebuild`, `stop` (reason, rounds), `run.done` (status, rounds, last_score) / `run.failed`;after the run: `pick.pairwise`, `pick.packaged`, `texture.skipped` / `texture.failed` (addons.select).diff --git a/harness/tests/orchestrator_tracks/test_orchestrator.py b/harness/tests/orchestrator_tracks/test_orchestrator.pyindex bf7da9cd..0c9866ac 100644--- a/harness/tests/orchestrator_tracks/test_orchestrator.py+++ b/harness/tests/orchestrator_tracks/test_orchestrator.py@@ -65,24 +65,26 @@ def test_fan_out_preserves_order_and_captures_exceptions():# ----------------------------------------------------------------------------- state + runnerdef test_run_state_roundtrip(tmp_ws):- st = RunState()- st.mark_round_done(0, "abc")+ st = RunState(status=RunStatus.REFINING, materialized_for="gemini-cli")st.save(tmp_ws)again = RunState.load(tmp_ws)- assert again is not None and again.current_round == 1 and again.round_commits[0] == "abc"- assert RunState.load_or_new(tmp_ws, resume=False).completed_rounds == []+ assert again is not None and again.status is RunStatus.REFINING and again.materialized_for == "gemini-cli"+ assert RunState.load_or_new(tmp_ws, resume=False).status is RunStatus.PLANNINGdef test_a_run_state_saved_before_2026_09_22_still_loads(tmp_ws):- """It named a best round and could end ``passed`` / ``plateau``: the keys are ignored- and the status reads as ``stopped`` — a resume goes on from the last round."""+ """It named a best round, cached the round journal and could end ``passed`` / ``plateau``:+ the keys are ignored and the status reads as ``stopped`` — a resume goes on from the+ journal's last round."""tmp_ws.state_path.write_text(json.dumps({"status": "passed", "stop_reason": "pass", "current_round": 2, "completed_rounds": [0, 1],"round_commits": {"0": "a0", "1": "a1"}, "best_round": 0, "best_commit": "a0", "best_score": 0.81,"best_considered_through": 1}))st = RunState.load(tmp_ws)- assert st is not None and st.status is RunStatus.STOPPED and st.round_commits == {0: "a0", 1: "a1"}- assert "best_round" not in st.model_dump() and RunStatus("plateau") is RunStatus.STOPPED+ assert st is not None and st.status is RunStatus.STOPPED and st.stop_reason == "pass"+ dumped = st.model_dump()+ assert not {"best_round", "completed_rounds", "round_commits", "current_round"} & set(dumped)+ assert RunStatus("plateau") is RunStatus.STOPPEDdef test_stage_runner_caches_by_input_hash(tmp_ws):diff --git a/harness/tests/orchestrator_tracks/test_resume_reconcile.py b/harness/tests/orchestrator_tracks/test_resume_reconcile.pyindex 98aa35ae..3a516fd1 100644--- a/harness/tests/orchestrator_tracks/test_resume_reconcile.py+++ b/harness/tests/orchestrator_tracks/test_resume_reconcile.py@@ -16,7 +16,7 @@ import pytestfrom codeverse3d.contracts.common import Languagefrom codeverse3d.contracts.run import RunStatus-from codeverse3d.orchestrator import RoundPolicy, RunState+from codeverse3d.orchestrator import RoundPolicyfrom codeverse3d.proc import EventLogfrom codeverse3d.tracks.lifecycle import SpecChangedfrom codeverse3d.tracks.static_object import StaticObjectTrack@@ -69,28 +69,25 @@ def completed_run(tmp_path, chair_plan, settings):# --------------------------------------------------------------------- (a) crash windowdef test_crash_between_round_write_and_state_save_ends_at_the_newer_round(completed_run):- """rNN.json + its commit are durable but mark_round_done lived only in memory until- the state save. A crash in that window left the state one round behind the journal- (and here the tree on the older round): the resume rebuilds the state from the journal- and the run ends on the LAST round."""+ """rNN.json + its commit are durable; the state save after them is not. A crash in that+ window — here with a state written before r01 (a pre-2026-09-22 one that still caches the+ journal one round short) and the tree on the older round — resumes from the JOURNAL: the+ history is r00 + r01 and the run ends on the LAST round."""run = completed_run(max_rounds=1)rec1, ws = run.record, run.wsassert len(rec1.rounds) == 2- # rewind state.json to what a crash between the r01 write and the state save leavesstate = json.loads(ws.state_path.read_text())- state["completed_rounds"], state["current_round"] = [0], 1- state["round_commits"] = {"0": rec1.rounds[0].commit}+ state.update(completed_rounds=[0], current_round=1, round_commits={"0": rec1.rounds[0].commit})ws.state_path.write_text(json.dumps(state))ws.restore(rec1.rounds[0].commit)ws.commit("stale tree")rec2 = run.rerun(resume=True)- assert [r.index for r in rec2.rounds] == [0, 1]+ assert [r.index for r in rec2.rounds] == [0, 1] and rec2.rounds[1].commit == rec1.rounds[1].commitassert "refine" in (ws.src / "model.py").read_text(), "round 1's code must be restored"- st = RunState.load(ws)- assert st.completed_rounds == [0, 1] and st.round_commits[1] == rec1.rounds[1].commit+ assert "completed_rounds" not in json.loads(ws.state_path.read_text()), "the state keeps no copy of the journal"ev = [e for e in EventLog(ws.events_path).read() if e["event"] == "resume.reconciled"]- assert ev and ev[-1]["state_was_stale"] is True and ev[-1]["restored_last_round"] == 1+ assert ev and ev[-1]["rounds"] == 2 and ev[-1]["restored_last_round"] == 1def test_an_old_run_that_restored_its_best_round_resumes_from_its_last(completed_run, settings):@@ -150,7 +147,6 @@ def test_a_planner_outage_on_resume_keeps_the_recorded_history(completed_run):assert saved["status"] == "failed" and "503 storm" in saved["error"]assert [r["index"] for r in saved["rounds"]] == [0], "a planner outage must not wipe the history"assert saved["rounds"][0]["commit"] == run.record.rounds[0].commit- assert RunState.load(ws).completed_rounds == [0]# --------------------------------------------------------------------- (d) force provenance@@ -198,8 +194,6 @@ def test_a_spec_edit_without_force_is_refused_before_anything_runs(completed_runassert p2.requests == [], "no model call before the refusal"assert not (ws.root / "rounds" / "pre_force").exists()assert (ws.root / "rounds" / "r00.json").is_file()- st = RunState.load(ws)- assert st.completed_rounds == [0]assert json.loads(ws.record_path.read_text())["status"] != "failed"# the sanctioned budget raise (outside the fingerprint) still resumes plainlydiff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.pyindex d5a37350..e8495708 100644--- a/harness/tests/orchestrator_tracks/test_tracks.py+++ b/harness/tests/orchestrator_tracks/test_tracks.py@@ -60,8 +60,7 @@ def test_static_track_end_to_end_agent_path(tmp_path, chair_plan, settings):assert [r.score for r in rec.rounds] == [0.55, 0.7, 0.85, 0.85]assert rec.total_usage.cost_usd > 0 and rec.extra["stop_reason"] == "max_rounds"assert ws.record_path.is_file() and ws.plan_path.is_file() and ws.state_path.is_file()- state = RunState.load(ws)- assert state.status is RunStatus.MAX_ROUNDS and state.completed_rounds == [0, 1, 2, 3]+ assert RunState.load(ws).status is RunStatus.MAX_ROUNDSassert services.materialized == ["fake"] and (ws.root / "AGENTS.md").is_file()kinds = [e["event"] for e in EventLog(ws.events_path).read()]for k in ("run.start", "stage.done", "plan.done", "round.start", "build.done", "gates.done", "judge.done", "round.done", "stop", "run.done"):