Skip to content

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.py
index 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 budget
first — 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.py
index 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 when
its 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 = ws
diff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.py
index 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 are
resuming 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 are
dropped (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 spec
state.extra["spec_fingerprint"] = fp
kept: list[RoundRecord] = []
dropped: list[int] = []
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 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 cac
is 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 the
scene 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 + one
re-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.md
index 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 frozen
3dcode 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.py
index 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_path
def _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):