A run normally starts only from a clean commit: source in the RunPlan is
{commit, dirty} and preflight, launch, the Supervisor and sealing refuse any
other checkout. A source overlay lets an outside author, such as an RSI
agent's evaluation, run its own tools on top of one committed base without
making a commit of it and without re-qualifying anything.
What may be replaced
Only files under ora/agent/toolkit/tools/, ora/policy/tool_surfaces/ and
ora/policy/task_files/ (a run's own task file, policy.task_file),
and policy.lock (regenerated over them). No file a qualification record
hashes lives there: the RoboDojo worker and play kernels,
ora/orchestrator/episode/action_executor.py, pyproject.toml, uv.lock and
the RoboTwin seed-scan inputs stay the base commit's, so card, task and lane
qualification records of the base commit still apply.
The overlay file
The checkout states its overlay in .ora-source-overlay.json at its root
(ignored by git):
{
"schema": "ora.source-overlay.v1",
"base_commit": "<the checkout's HEAD, 40 hex>",
"files": {"ora/agent/toolkit/tools/move_to/tool.py": "<sha256>", "...": null},
"provenance": {"agent_repo": "...", "agent_commit": "..."}
}
files lists every path that differs from the base commit, with the sha256 of
its bytes, or null for a path removed from the base. provenance is recorded
as given. New files must be staged (git add) so that ./scripts/ora lock
covers them; staging does not change the check below.
The check
ora.orchestrator.spec.source_overlay.source_state accepts the checkout when
HEAD is base_commit and every difference from HEAD (tracked, staged or
untracked, as git status --untracked-files=all lists it) is a listed path
whose bytes match. Plan resolution then records source as the base commit,
clean, and the overlay whole, with the sha256 of its canonical JSON, as the
plan's source_overlay block, which the plan hash covers. Preflight
(source_identity), launch, the Supervisor and sealing require the same
overlay again. Without the file, nothing changes: a checkout that differs from
its commit is dirty and refused, as before.
To reproduce a run, check out its source.commit, restore the files of
source_overlay.files and write the overlay file back.