nexu-io/open-design · error · SystemExit

running-left mirror job is missing an approved mirror_decisi

Error message

running-left mirror job is missing an approved mirror_decision; use derive_running_left_from_running_right.py after visual review

What it means

A mirror job must carry mirror_decision: {"approved": true, ...} written by the derive script after explicit visual confirmation (--confirm-appropriate-mirror + --decision-note). This enforces that mirroring was a deliberate, reviewed decision rather than a hand-edit.

Source

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

    source_hash = file_sha256(source)
    output_hash = file_sha256(output)
    if source_hash != expected_hash:
        raise SystemExit(f"job {job_id} source image hash does not match imagegen-jobs.json")
    if output_hash != expected_hash:
        raise SystemExit(
            f"job {job_id} decoded output does not match its recorded source image; "
            "do not rewrite decoded visual outputs locally"
        )


def validate_mirror_hash(job: dict[str, object], *, source: Path, output: Path, job_id: str) -> None:
    if job_id != "running-left":
        raise SystemExit(f"job {job_id} may not use deterministic mirror provenance")
    if job.get("derived_from") != "running-right":
        raise SystemExit("running-left mirror job must derive from running-right")
    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")

View on GitHub (pinned to 5be4028344)

Solutions

Run derive_running_left_from_running_right.py with --confirm-appropriate-mirror and a non-empty --decision-note, after visually verifying the right strip mirrors cleanly.
Do not hand-write mirror_decision — the derive script produces it atomically with the hashes.
Re-run finalize_pet_run.py.

Defensive patterns

Strategy: type-guard

Validate before calling

import json
from pathlib import Path

manifest = json.loads(Path("<run_dir>/imagegen-jobs.json").read_text())
left = next(j for j in manifest["jobs"] if j.get("id") == "running-left")
if left.get("source_provenance") == "deterministic-mirror":
    decision = left.get("mirror_decision")
    assert isinstance(decision, dict) and decision.get("approved") is True, \
        "run derive_running_left_from_running_right.py with --confirm-appropriate-mirror first"

Type guard

def mirror_decision_ok(left_job: dict) -> bool:
    decision = left_job.get("mirror_decision")
    return isinstance(decision, dict) and decision.get("approved") is True

Prevention

Never mark running-left complete by hand; run the derive script so it records an approved mirror_decision.
Treat the visual review + --confirm-appropriate-mirror + --decision-note as mandatory.
Validate mirror_decision before invoking finalize.

When it happens

Trigger: mirror_decision is absent, not a dict, or its approved field is not exactly True — typically because the manifest was edited to mark running-left complete without running the derive script.

Common situations: Skipping the derive script and hand-writing status=complete; an interrupted derive that wrote provenance but not the decision; copy-pasting from another job.

Related errors

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