[dmccoystephenson]

Summary

Stage B characterization test plus the matching README note, covering a path that had neither: what happens when environmentService.create_environment fails.

• tests/test_main.py: test_a_failed_creation_propagates_without_recording_the_environment asserts the current behaviour. The exception propagates out of main(), a pre-existing environments.json entry is left untouched and no new one is added, no environment-created event is reported, and the render loop is never entered.
• README.md (Running): a paragraph after the failed-load note states that creation is not guarded in the same way. The program exits with a traceback and a non-zero status, the cache and usage report are unaffected, and create_environments.bat depends on that status to print its Error occurred… line, with the traceback going to error_log.txt.

No production code is changed. The test deliberately makes no assertion about window.close(), which is not called on this path, unlike the failed-load path. That asymmetry looks unintended, so it was filed as #42 for an owner decision and was not locked in by the test.

No tracking issue covers this. The gap was found during triage.

Skipped issues

• The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41: deciding whether to bump the Viron submodule (and add bearer-token support) or keep the pin is a project decision, and re-pointing the submodule needs explicit authorization.
• Decide whether per-location colours should be stable across frames #24: needs an owner decision (stable vs. animated colours).
• Support drawing environments with multiple grids #2 and Add text-based UI support to library for users #11: feature work too large for a polish-sized cycle.
• A failed environment creation leaves the window open and shows no error, unlike a failed load #42: filed this cycle and needs an owner decision.

Test plan

• python3 -m py_compile main.py graphik.py __init__.py: passes
• python3 -m unittest discover -s tests: ran 124 tests, OK (123 before, plus 1 new)
• README claims traced to main.py (no try around create_environment; the cache write and usage.report come after it), to Viron's environmentService.py (raise_for_status()), and to create_environments.bat (if errorlevel 1)
• Interactive render check: UNVERIFIED-not-applicable, because no rendering or service-call file is modified

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (anchored on CI run 38877431961, test job: pass, and the local python3 -m unittest discover -s tests run: 124 tests, OK):

• Scope: PASS. Only README.md (one paragraph) and tests/test_main.py (one test) are modified, and both cover the failed-creation path.
• Tests-new: PASS. No new public functions are added. The new test characterizes an existing path in main() that had no test.
• Tests-fix: N/A. No bug fix is included. The suspected defect (no window.close() on a failed creation) was filed as A failed environment creation leaves the window open and shows no error, unlike a failed load #42 rather than fixed, and the test deliberately makes no assertion about it.
• Sibling structure: PASS. The test sits in TestEnvironmentCreation, uses the MainTestCase helpers (writeCacheFile, readCacheFile, runMain), and follows the naming of test_a_failed_load_reports_the_error_and_closes_the_window.
• Sibling renames: N/A. Nothing is renamed.
• Docs: PASS. The paragraph is placed right after the failed-load note it contrasts with. Every claim was traced: there is no try around create_environment in main.py, the cache write and usage.report follow the call, Viron's create_environment calls raise_for_status(), and create_environments.bat branches on if errorlevel 1.
• Issue resolution: N/A. No Closes reference is made.
• Manual validation: PASS for py_compile and the unit suite on the PR head. The interactive render is UNVERIFIED-not-applicable, because no rendering or service-call file is touched.

Judgment call, not blocking: "the program exits with a traceback" describes the CLI. A direct main() caller instead receives the exception, and the following sentence about main() raising already covers that. The wording was left as is because the paragraph sits in the CLI-focused Running section.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson