Skip to content

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.py
index 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.PLANNING
stages: 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.py
index 3f0824dc..ced6406b 100644
--- a/harness/codeverse3d/tracks/lifecycle.py
+++ b/harness/codeverse3d/tracks/lifecycle.py
@@ -292,11 +292,9 @@ class BaseTrack:
# ------------------------------------------------------------------ resume reconciliation
def 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 are
dropped (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 before
2026-09-22, which restored its best round. The next round refines the round
before 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 = [], {}, 0
state.extra["spec_fingerprint"] = fp
kept: 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.ok
return _stop(RunStatus.JUDGE_UNAVAILABLE if unjudged else RunStatus.NO_REFINE_TASKS)
- ctx.state.current_round = index
ctx.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 and
deliver ONE no-generation round. Any failure here is swallowed: the run is
already 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 salvage
grace_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}")
return
rounds.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.md
index 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-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 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.json
measurement.json … — the LAST round's build; graphics: frames/fNN_tT.png frames_sheet.png
preview.gif metrics.json; texturing (a pick's --texture): object_textured.glb
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 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.py
index 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 + runner
def 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.PLANNING
def 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.STOPPED
def 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.py
index 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 pytest
from codeverse3d.contracts.common import Language
from codeverse3d.contracts.run import RunStatus
-from codeverse3d.orchestrator import RoundPolicy, RunState
+from codeverse3d.orchestrator import RoundPolicy
from codeverse3d.proc import EventLog
from codeverse3d.tracks.lifecycle import SpecChanged
from codeverse3d.tracks.static_object import StaticObjectTrack
@@ -69,28 +69,25 @@ def completed_run(tmp_path, chair_plan, settings):
# --------------------------------------------------------------------- (a) crash window
def 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.ws
assert len(rec1.rounds) == 2
- # rewind state.json to what a crash between the r01 write and the state save leaves
state = 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].commit
assert "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"] == 1
def 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_run
assert 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 plainly
diff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.py
index 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_ROUNDS
assert 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"):