nexu-io/open-design · error · SystemExit

running-left mirror source must be decoded/running-right.png

Error message

running-left mirror source must be decoded/running-right.png

What it means

Raised by validate_mirror_hash when the running-left mirror job's source_path does not point at decoded/running-right.png. The deterministic mirror is only valid when it derives from the canonical right-facing strip, so the script enforces both filename and parent directory name.

Source

Thrown at skills/hatch-pet/scripts/finalize_pet_run.py:104

    decision = job.get("mirror_decision")
    if not isinstance(decision, dict) or decision.get("approved") is not True:
        raise SystemExit(
            "running-left mirror job is missing an approved mirror_decision; "
            "use derive_running_left_from_running_right.py after visual review"
        )

    expected_source_hash = job.get("source_sha256")
    expected_output_hash = job.get("output_sha256")
    if not isinstance(expected_source_hash, str) or not expected_source_hash:
        raise SystemExit("running-left mirror job is missing source_sha256")
    if not isinstance(expected_output_hash, str) or not expected_output_hash:
        raise SystemExit("running-left mirror job is missing output_sha256")
    if not source.is_file():
        raise SystemExit(f"running-left mirror source image no longer exists: {source}")
    if not output.is_file():
        raise SystemExit(f"running-left mirrored output is missing: {output}")
    if source.name != "running-right.png" or source.parent.name != "decoded":
        raise SystemExit("running-left mirror source must be decoded/running-right.png")
    if output.name != "running-left.png" or output.parent.name != "decoded":
        raise SystemExit("running-left mirror output must be decoded/running-left.png")
    if file_sha256(source) != expected_source_hash:
        raise SystemExit("running-left mirror source hash does not match imagegen-jobs.json")
    if file_sha256(output) != expected_output_hash:
        raise SystemExit(
            "running-left mirrored output hash does not match imagegen-jobs.json; "
            "rerun derive_running_left_from_running_right.py"
        )
    with Image.open(source) as source_image, Image.open(output) as output_image:
        expected = ImageOps.mirror(source_image.convert("RGBA"))
        actual = output_image.convert("RGBA")
        if expected.size != actual.size or expected.tobytes() != actual.tobytes():
            raise SystemExit(
                "running-left mirrored output is not an exact horizontal mirror of running-right"
            )

View on GitHub (pinned to 5be4028344)

Solutions

Set the running-left job's source_path to decoded/running-right.png (relative to run_dir) in imagegen-jobs.json.
Ensure the decoded/ directory exists and contains running-right.png produced by the base/running-right imagegen job.
Re-derive running-left via derive_running_left_from_running_right.py, which records the correct source path.

Example fix

// before (imagegen-jobs.json)
"source_path": "raw/running-right.png"
// after
"source_path": "decoded/running-right.png"

Defensive patterns

Strategy: validation

Validate before calling

source = (run_dir / job['source_path']).resolve()
if source.name != 'running-right.png' or source.parent.name != 'decoded':
    raise ValueError('mirror source must be decoded/running-right.png')

Prevention

Never hand-edit the running-left job's source_path; let the derive script record it.
Keep the decoded/ directory name stable; do not rename it.
Validate manifest path conventions with a lint pass before finalizing.

When it happens

Trigger: job['source_path'] for the running-left job resolves to a file whose .name != 'running-right.png' or whose parent .name != 'decoded'. Happens when the manifest was hand-edited or the source was copied to a different name/location.

Common situations: Editing imagegen-jobs.json to repoint the mirror source; renaming the decoded directory; running a derive script that wrote running-right.png into raw/ instead of decoded/.

Related errors

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/6e6635751fefafbb. Report an issue: GitHub.