fix(smoke): pass --python-exit-code 1 so an uncaught exception is red

Blender exits 0 when a --python script raises unless --python-exit-code is
set, and protocol.classify maps exit 0 to PASS. Module-level failures
(imports, the gallery_framing sys.path shim, check_extension_template's
register()) were silent greens.

- run_example.build_cmd, every direct Blender call in blender-smoke.yml, and
  the subprocess calls in render_hero, measure_hero_drift, asset_sheet and
  check_falsifier_targets now pass --python-exit-code 1 before --python.
- New canary tests/smoke/canary_raise.py + workflow step: must exit 1.
- test_harness: build_cmd carries the flag ahead of --python.

Proof (local, .scratch/blender-5.2.1-windows-x64/blender.exe, "Blender 5.2.1 LTS"):
before: run_example on a module-level raise printed [PASS], exit 0.
after:  [FAIL] canary-raise: blender exit 1, exit 1; canary-sidecar still [PASS].

Closes #319

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/blender-smoke.yml

@@ -181,18 +181,18 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p "$RUNNER_TEMP/out"
-          xvfb-run -a "$BLENDER" --background --python tests/smoke/run_smoke.py -- "$RUNNER_TEMP/out"
+          xvfb-run -a "$BLENDER" --background --python-exit-code 1 --python tests/smoke/run_smoke.py -- "$RUNNER_TEMP/out"
 
       - name: Build template input scene
         run: |
           set -euo pipefail
-          xvfb-run -a "$BLENDER" --background --python tests/smoke/make_input.py -- "$RUNNER_TEMP/out/input.blend"
+          xvfb-run -a "$BLENDER" --background --python-exit-code 1 --python tests/smoke/make_input.py -- "$RUNNER_TEMP/out/input.blend"
 
       - name: Headless glTF template runs (exit 0, .glb produced)
         run: |
           set -euo pipefail
           xvfb-run -a "$BLENDER" --background "$RUNNER_TEMP/out/input.blend" \
-            --python templates/headless-batch-script-template/script.py -- \
+            --python-exit-code 1 --python templates/headless-batch-script-template/script.py -- \
             --output "$RUNNER_TEMP/out/out.glb" --apply-modifier SUBSURF
           test -s "$RUNNER_TEMP/out/out.glb" || { echo "::error::glTF output missing/empty"; exit 1; }
           head -c4 "$RUNNER_TEMP/out/out.glb" | grep -q "glTF" || { echo "::error::not a glTF binary"; exit 1; }
@@ -201,7 +201,7 @@ jobs:
         run: |
           set +e
           xvfb-run -a "$BLENDER" --background "$RUNNER_TEMP/out/empty.blend" \
-            --python templates/headless-batch-script-template/script.py -- --output "$RUNNER_TEMP/out/none.glb"
+            --python-exit-code 1 --python templates/headless-batch-script-template/script.py -- --output "$RUNNER_TEMP/out/none.glb"
           code=$?
           set -e
           [ "$code" -eq 2 ] || { echo "::error::expected exit 2 for no-mesh input, got $code"; exit 1; }
@@ -215,15 +215,15 @@ jobs:
       - name: Build pipeline template fixture GLB
         run: |
           set -euo pipefail
-          xvfb-run -a "$BLENDER" --background --python tests/smoke/make_pipeline_glb.py -- \
+          xvfb-run -a "$BLENDER" --background --python-exit-code 1 --python tests/smoke/make_pipeline_glb.py -- \
             "$RUNNER_TEMP/out/pipeline_src.glb"
           test -s "$RUNNER_TEMP/out/pipeline_src.glb" || { echo "::error::pipeline fixture missing"; exit 1; }
 
       - name: Headless AI asset pipeline template runs (exit 0, LODs produced)
         run: |
           set -euo pipefail
           mkdir -p "$RUNNER_TEMP/out/pipeline"
-          xvfb-run -a "$BLENDER" --background --python templates/ai-asset-pipeline-template/pipeline.py -- \
+          xvfb-run -a "$BLENDER" --background --python-exit-code 1 --python templates/ai-asset-pipeline-template/pipeline.py -- \
             --input "$RUNNER_TEMP/out/pipeline_src.glb" \
             --outdir "$RUNNER_TEMP/out/pipeline" \
             --preset unity \
@@ -236,7 +236,7 @@ jobs:
       - name: Headless pipeline template missing input returns exit 2
         run: |
           set +e
-          xvfb-run -a "$BLENDER" --background --python templates/ai-asset-pipeline-template/pipeline.py -- \
+          xvfb-run -a "$BLENDER" --background --python-exit-code 1 --python templates/ai-asset-pipeline-template/pipeline.py -- \
             --input "$RUNNER_TEMP/out/does-not-exist.glb" \
             --outdir "$RUNNER_TEMP/out/pipeline" \
             --preset unity
@@ -251,7 +251,7 @@ jobs:
           # Cycles (CPU) so this is reliable on GPU-less runners; the EEVEE-id regression
           # itself is gated in run_smoke.py via engine assignment.
           xvfb-run -a "$BLENDER" --background "$RUNNER_TEMP/out/input.blend" \
-            --python tests/smoke/tmpl_render.py -- \
+            --python-exit-code 1 --python tests/smoke/tmpl_render.py -- \
             --output "$RUNNER_TEMP/out/render.png" --engine CYCLES
           test -s "$RUNNER_TEMP/out/render.png" || { echo "::error::render PNG missing/empty"; exit 1; }
 
@@ -281,6 +281,20 @@ jobs:
           [ "$code" -eq 1 ] || { echo "::error::unexpected skip did not fail (got $code)"; exit 1; }
           echo "unexpected skip exited 1 (correct)"
 
+      - name: Canary - uncaught exception is red
+        run: |
+          set +e
+          python3 tests/smoke/run_example.py --no-record \
+            --name canary-raise \
+            --blender "$BLENDER" \
+            --script tests/smoke/canary_raise.py \
+            --series "${{ matrix.series }}" \
+            --xvfb
+          code=$?
+          set -e
+          [ "$code" -eq 1 ] || { echo "::error::uncaught exception did not fail (got $code)"; exit 1; }
+          echo "uncaught exception exited 1 (correct)"
+
       - name: Canary - post-exit sidecar
         run: |
           set -euo pipefail

scripts/asset_sheet.py

@@ -160,7 +160,7 @@ def render_panel(blender: str, entry: dict, png: Path) -> bool:
         env = dict(os.environ, BDT_SHEET_SCRIPT=str(script), BDT_SHEET_SELECT=inc,
                    BDT_SHEET_EXCLUDE=exc or "", BDT_SHEET_OUT=str(png))
         proc = subprocess.run(
-            [blender, "--background", "--factory-startup", "--python",
+            [blender, "--background", "--factory-startup", "--python-exit-code", "1", "--python",
              str(REPO / "scripts" / "asset_sheet_panel.py"), "--", *cmd],
             capture_output=True, text=True, encoding="utf-8", errors="replace",
             cwd=REPO, env=env,

scripts/measure_hero_drift.py

@@ -169,7 +169,7 @@ def main(argv=None) -> int:
             png.unlink()
         t0 = time.time()
         proc = subprocess.run(
-            [blender, "--background", "--factory-startup", "--python", str(script), "--", *cmd],
+            [blender, "--background", "--factory-startup", "--python-exit-code", "1", "--python", str(script), "--", *cmd],
             capture_output=True, text=True, encoding="utf-8", errors="replace", cwd=REPO,
         )
         secs = time.time() - t0

scripts/render_hero.py

@@ -71,7 +71,7 @@ def main(argv=None) -> int:
                 continue
             script = next((REPO / e["dir"]).glob("*.py"))
             proc = subprocess.run(
-                [blender, "--background", "--factory-startup", "--python", str(script),
+                [blender, "--background", "--factory-startup", "--python-exit-code", "1", "--python", str(script),
                  "--", *cmd],
                 capture_output=True, text=True, encoding="utf-8", errors="replace", cwd=REPO,
             )

tests/check_falsifier_targets.py

@@ -228,7 +228,7 @@ def check_runtime(blender, only=None):
         for flag, (want, _target) in sorted(falsifiers.items()):
             checked += 1
             proc = subprocess.run(
-                [blender, "--background", "--python", script, "--", flag],
+                [blender, "--background", "--python-exit-code", "1", "--python", script, "--", flag],
                 capture_output=True,
             )
             got = proc.returncode

tests/smoke/canary_raise.py

@@ -0,0 +1,7 @@
+"""Harness canary: raise at module level, outside any FATAL wrapper.
+
+Without --python-exit-code Blender exits 0 here and the harness would record
+PASS. The workflow runs this with --no-record and requires exit 1. Not a
+shipped example.
+"""
+raise RuntimeError("harness canary: uncaught exception must be red")

tests/smoke/run_example.py

@@ -33,7 +33,7 @@ def append_status(path, record):
 
 
 def build_cmd(args):
-    cmd = [args.blender, "--background", "--python", args.script, "--"]
+    cmd = [args.blender, "--background", "--python-exit-code", "1", "--python", args.script, "--"]
     cmd.extend(args.script_args)
     if args.xvfb:
         cmd = ["xvfb-run", "-a"] + cmd

tests/smoke/test_harness.py

@@ -171,6 +171,27 @@ def test_exit_pre_row_has_sidecar_and_floor(self):
         self.assertEqual(row["sidecar_contains"], "exit_pre-ok")
 
 
+class BuildCmd(unittest.TestCase):
+    """Blender exits 0 on an uncaught exception unless --python-exit-code is set."""
+
+    def _cmd(self, xvfb=False):
+        import argparse
+
+        import run_example
+
+        ns = argparse.Namespace(blender="bl", script="s.py", script_args=["--x"], xvfb=xvfb)
+        return run_example.build_cmd(ns)
+
+    def test_exit_code_flag_precedes_python(self):
+        cmd = self._cmd()
+        i = cmd.index("--python-exit-code")
+        self.assertEqual(cmd[i + 1], "1")
+        self.assertLess(i, cmd.index("--python"))
+
+    def test_xvfb_keeps_exit_code_flag(self):
+        self.assertIn("--python-exit-code", self._cmd(xvfb=True))
+
+
 class RunCatalog(unittest.TestCase):
     """run_catalog runs every row and reports all failures; empty is red."""