Official Codebase of 3DCodeVerse
Python
lifecycle: resume --force archives the rounds even when the spec is unchanged — the one way to regenerate a frozen stage (Q2)
gaoypeng79abdb6983f7
diff --git a/harness/codeverse3d/cli/main.py b/harness/codeverse3d/cli/main.pyindex bd5e121c..652ff504 100644--- a/harness/codeverse3d/cli/main.py+++ b/harness/codeverse3d/cli/main.py@@ -591,9 +591,9 @@ def resume(bool,typer.Option("--force",- help="re-enter a run that already finished (it will be re-planned and re-scored), "- "and allow resuming after a spec edit — the old rounds and record are archived "- "under rounds/pre_force/ and the run re-plans from the edited spec",+ help="start the run again from round 0: the old rounds and record are ALWAYS archived "+ "under rounds/pre_force/ (so drifted pre-round stages regenerate); also re-enters a "+ "finished run and allows resuming after a spec edit (the run then re-plans)",),] = False,no_pick: Annotated[bool, typer.Option("--no-pick", help="do not pick + package a round afterwards")] = False,@@ -602,8 +602,8 @@ def resume(``--max-minutes`` / ``--rounds`` rewrite the spec's budgetfirst — the only way to continue a BUDGET-stopped run. A run that already- reached a terminal state is refused unless ``--force``: re-entering it spends- money and overwrites its final state."""+ reached a terminal state is refused unless ``--force``, which archives its rounds+ (``rounds/pre_force/``) and starts it again at round 0 — paid, and a new final state."""ws = C.open_workspace(slug, runs_dir)# the run mutex, before the spec is rewritten (a budget raise is a mutation)with C.mutating(ws, what=f"3dcode resume {ws.root.name}"):diff --git a/harness/codeverse3d/orchestrator.py b/harness/codeverse3d/orchestrator.pyindex 3557d703..67685e0e 100644--- a/harness/codeverse3d/orchestrator.py+++ b/harness/codeverse3d/orchestrator.py@@ -123,8 +123,9 @@ class StageRunner:``frozen`` (the run already has rounds): a stage with a recorded result serves it even whenits key drifted (``stage.frozen``) — the rounds refined what it wrote, and re-running it would- re-pay its session and overwrite that work. ``resume --force`` archives the rounds, and is- the one way to regenerate a stage under them."""+ re-pay its session and overwrite that work. ``resume --force`` archives the rounds to+ ``rounds/pre_force/`` whether or not the spec changed (``reconcile_resume``), so the run starts+ again at round 0 unfrozen — the one way to regenerate a stage under existing rounds."""def __init__(self, ws: Workspace, events: EventLog, state: RunState | None = None, *, frozen: bool = False):self.ws = wsdiff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.pyindex 419b0e48..30331c58 100644--- a/harness/codeverse3d/tracks/lifecycle.py+++ b/harness/codeverse3d/tracks/lifecycle.py@@ -356,8 +356,11 @@ class BaseTrack::func:`plan_stage_inputs`, stamped on first run) must match the spec we areresuming with; budget raises are outside the fingerprint by construction.On a mismatch a plain resume raises :class:`SpecChanged`; ``--force``- emits ``resume.spec_changed`` and archives the old journal + ``record.json``- to ``rounds/pre_force/`` — old rounds are never paired with a new spec/plan.+ emits ``resume.spec_changed`` and re-plans — old rounds are never paired with a+ new spec/plan. ``--force`` archives the old journal + ``record.json`` to+ ``rounds/pre_force/`` whether the spec changed or not: with no rounds left the+ pre-round stages are no longer frozen (``StageRunner.frozen``), so this is the+ one way to regenerate a stage whose key drifted under existing rounds.2. **Journal integrity.** Trailing rounds whose commit git does not have aredropped (half-written journal), with a ``resume.dropped_rounds`` event.3. **The tree.** The working tree goes back on the LAST round's commit when anything@@ -385,10 +388,11 @@ class BaseTrack:)events.emit("resume.spec_changed", old_fingerprint=stored, new_fingerprint=fp,archived_rounds=len(journal))+ state.stages.pop("plan", None) # the plan must be rebuilt from the edited spec+ if force and (journal or ws.record_path.is_file()):archived = self._archive_pre_force(ws)- events.emit("resume.archived", dest=str(archived))+ events.emit("resume.archived", dest=str(archived), rounds=len(journal))journal = []- state.stages.pop("plan", None) # the plan must be rebuilt from the edited specstate.extra["spec_fingerprint"] = fpkept: list[RoundRecord] = []dropped: list[int] = []diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex ba8ebf7f..c8800e84 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -481,8 +481,9 @@ run's minutes, a failing sibling raised after every sibling has finished and cacis not cached — it runs every session. Every other stage is cached under its key(`stages/<name>.json`): what its result depends on, named in the declaration. **Once rounds exist**a recorded stage is served whatever its key (`stage.frozen`), and the skeleton (`seeds_src`) never-runs at all; `3dcode resume --force` (which archives the rounds) is the one way to regenerate a-stage under them. The plan itself is `run()`'s, before the graph (`plan_stage_key`). What the+runs at all; `3dcode resume --force` is the one way to regenerate a stage under them: it archives+the round journal + `record.json` to `rounds/pre_force/` whether or not the spec changed, and the run+starts again at round 0 with no stage frozen. The plan itself is `run()`'s, before the graph (`plan_stage_key`). What thescene stages do: `assets` — both kinds climb one ladder (single-shot → check → one repair → agent;blender_glb heroes get a sub-workspace with the static planner's parts + asset_v1 judge + onere-judged fix pass, undone when worse; a degraded asset verdict leaves score None / judged False,diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex e0ac476a..de463648 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -167,7 +167,9 @@ unless you type `--host` yourself; it never serves a path outside the declared r# the money is the ledger's, and the step log (the run's minutes) carries on.# Once rounds exist a recorded stage never runs again: one whose key drifted (a# code change to what it hashes) serves its recorded result (`stage.frozen`); only- # `resume --force` — which archives the rounds — regenerates a stage under them+ # `resume --force` regenerates a stage under them: it ALWAYS archives the round+ # journal + record.json to rounds/pre_force/ (spec changed or not) and the run+ # starts again at round 0, no stage frozen3dcode pick <slug> [--by score|pairwise] [--round N] [--texture] [--judge MODEL]# hand over a round: deliverable/ + selection.json (addons/select). score =# highest effective score, ties → fewer gate errors → the earlier round;diff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.pyindex c95d0d23..e2ba42bb 100644--- a/harness/tests/orchestrator_tracks/test_tracks.py+++ b/harness/tests/orchestrator_tracks/test_tracks.py@@ -282,8 +282,8 @@ def test_scene_children_are_stages_and_a_failed_env_never_repays_assets(tmp_pathdef _mood_replanned(tmp_path, settings, name, *, force):- """A scene run with r00, whose plan then changes ONLY in `mood`; resumed, after archiving the- rounds the way `resume --force` does when ``force``. Returns (resumed job labels, event names)."""+ """A scene run with r00, whose plan then changes ONLY in `mood` (the spec does not change); resumed,+ with ``--force`` when ``force``. Returns (resumed job labels, event names)."""plan = _small_scene_plan()spec = make_spec(Track.SCENE, Language.SCENE_THREEJS, max_rounds=0)ws = Workspace(tmp_path / "runs" / name)@@ -298,20 +298,20 @@ def _mood_replanned(tmp_path, settings, name, *, force):assert data["result"]["mood"] != "desolate, horror"data["result"]["mood"] = "desolate, horror"stage_file.write_text(json.dumps(data))- if force:- SceneTrack._archive_pre_force(ws)agent.jobs.clear()n_events = len(EventLog(ws.events_path).read())- mk().run(spec, ws, resume=True)+ mk().run(spec, ws, resume=True, force=force)return [j.label for j in agent.jobs], [e["event"] for e in EventLog(ws.events_path).read()[n_events:]]def test_a_mood_only_replan_invalidates_the_env_stage(tmp_path, settings):"""Review-3 V4a: the stage key is the whole plan, so a re-plan differing only in`mood` misses the cache (it used to serve an env generated under the old mood) — once the- rounds are archived, as `resume --force` does."""- labels, _ = _mood_replanned(tmp_path, settings, "harbour4", force=True)+ rounds are archived — which `resume --force` does even when the spec is unchanged (Q2)."""+ labels, events = _mood_replanned(tmp_path, settings, "harbour4", force=True)assert "env" in labels # a stale cached env must not be served+ assert "resume.archived" in events and "resume.spec_changed" not in events and "stage.frozen" not in events+ assert (tmp_path / "runs" / "harbour4" / "rounds" / "pre_force" / "r00.json").is_file()def test_a_drifted_stage_key_never_reruns_a_stage_under_existing_rounds(tmp_path, settings):