[dmccoystephenson]

Summary

• viron_address.py is added, with getVironAddress(), which reads PATCHWORK_VIRON_URL and PATCHWORK_VIRON_PORT. Pygame is not imported, so console_view.py can use it, and http://localhost:9999 remains the default.
• main.py and console_view.py read the address from it. Their url and port constants are removed.
• A variable that is unset, empty or blank leaves its default. A trailing slash on the URL is dropped, because Viron's services append :<port>/api/... to it and the port would otherwise land in the path. An invalid port prints a message and falls back to 9999, as an invalid grid size does in parseArgs.
• The README's Starting Viron section states how the address is changed.

The PATCHWORK_ prefix follows PATCHWORK_USAGE_REPORTING_KEY.

environments.json records environments by grid size alone, so a cache written against one Viron would be read against another once the address changes. That could fail to load, or resolve to an unrelated environment with the same ID. The README now says to delete the file or use another working directory. The file format was left alone as out of scope for #60.

Viron, render_window.py, graphik.py and the workflow file are unchanged. headless_run.py changes only in a docstring.

Closes #60

Test plan

• python3 -m unittest discover -s tests: 205 tests executed, all passing, 13 of them new
• python3 -m py_compile on every top-level module, including viron_address.py
• python3 headless_run.py: all three scenarios PASS
• Real HTTP, with main.py and console_view.py unmodified: both entry points were run through the real LocationService and EnvironmentService against local stand-in servers on :9999 and :18099. main() ran with --exit-after-create on the real Pygame under SDL's dummy driver. With no variables set, requests arrived on :9999. With PATCHWORK_VIRON_URL=http://127.0.0.1/ and PATCHWORK_VIRON_PORT=18099, requests arrived on :18099 only. With PATCHWORK_VIRON_PORT=nope, the message was printed and requests arrived on :9999
• Mutation check: hardcoding the old address in main.py and console_view.py, and removing the trailing-slash handling, failed exactly 3 tests. The source was then restored and the suite re-run
• Live Viron: UNVERIFIED. python3 main.py 10 --exit-after-create could not be run against a real server here

Why this PR is held for a human

The address passed to LocationService and EnvironmentService in main() is changed, so this diff touches a service call site, and Phase 4 of the dev loop requires the live anchor for that. The anchor did not run, so the pre-authorized merge was not used.

Three limits of the substitute should be known:

• Python 3.8 cannot import EnvironmentService, so the unmodified source was compiled in a scratch script with postponed annotations.
• The stand-in servers' JSON was written from the pinned submodule's models, not observed from a running Viron. The diff cannot change the response shape, but a mismatch would not have been detected.
• The scratch script is not committed.

For the reviewer, a run of python main.py 10 --exit-after-create against a local Viron with no variables set covers the default. Setting PATCHWORK_VIRON_PORT to anything else should then fail to connect, which confirms the override is honoured.

Notes for review

• viron_address.py joins the README's exceptions to the workflow's py_compile list, for the same reason as the two modules in The workflow's py_compile step omits text_renderer.py and console_view.py #61, and a comment there records the third. The suite imports it, so a syntax error still fails CI.
• getVironAddress() is called in main() even when both services are supplied, so an invalid port prints its message there too. The simpler call was kept over a guard for that case.
• Bearer tokens (The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41) are not added.

Issues not picked

• The workflow's py_compile step omits text_renderer.py and console_view.py #61: changing .github/workflows/ needs a human merge, and that PR would have held up every later cycle while gaining no coverage.
• A failed environment creation leaves the window open and shows no error, unlike a failed load #42, Decide whether per-location colours should be stable across frames #24, The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41: each is gated on an owner decision that has not been recorded.
• Support drawing environments with multiple grids #2: too large for this PR, since Location carries no grid ID.

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, scored against head a0cf233:

• Scope: FAIL, then fixed. The first head, 4a72544, altered the spacing of the usage line in main.py and console_view.py (usage ="Usage...), an unrelated change introduced while the constants above them were removed. It was found on reading the full diff, and a0cf233 restores both lines. Every remaining change serves The Viron address is hardcoded in both entry points #60. headless_run.py changes only because its docstring named the hardcoded address.
• Tests-new: PASS. getVironAddress and parsePort are exercised by 10 tests in tests/test_viron_address.py. Both entry points are tested with the default and the override, in tests/test_main.py and tests/test_console_view.py.
• Tests-fix: not applicable, since The Viron address is hardcoded in both entry points #60 is not a bug fix. As a substitute, hardcoding the old address in main.py and console_view.py and removing the trailing-slash handling failed exactly 3 tests, one for each mutation. The port range and whitespace handling were not mutated.
• Sibling structure: PASS. viron_address.py uses a snake_case filename, camelCase functions and Args/Returns docstrings. Its uppercase variable-name constants match KEY_ENV_VAR in usage_reporting.py.
• Sibling renames: not applicable, since nothing is renamed.
• Docs: PASS. The README's Starting Viron, Text rendering, Running and Running the tests sections were updated. No .bat script changes, as neither main.py's arguments nor their commands changed.
• Issue resolution: PASS. Both entry points read one source, http://localhost:9999 stays the default, a unit test covers the default and the override, and Starting Viron states how the address is changed.
• Manual validation: UNVERIFIED for the live anchor, which blocks merge. The substitutes pass: 205 tests, headless_run.py in all three scenarios, and the real-HTTP run described in the PR body.

Findings:

• main.py:102 — judgment call, left as is: getVironAddress() runs even when both services are supplied, so an invalid port is reported on a path that does not use it.
• viron_address.py:29 — judgment call for the reviewer: an invalid port falls back to 9999 instead of stopping. This matches parseArgs, but a mistyped port could reach the local Viron and not the one intended. The message is printed in that case, and PATCHWORK_VIRON_URL is still honoured.
• viron_address.py:44 — no scheme check is made on the URL. A value such as viron.example fails later, when Requests rejects it. The README says the scheme is required.
• README.md:196 — environments.json is not keyed by server. This risk is created by this PR and is documented rather than fixed. A follow-up issue is filed.
• tests/test_console_view.py:103 — the existing default-address test does not clear the new variables, so it would fail in a shell where they are set.
• The README example uses POSIX syntax, while the bundled scripts are Windows batch files. No PowerShell or cmd form is given.

Do-not-auto-merge check: no .github/workflows/*, security/ or .gitmodules path is modified, and no file loses more than 50 lines. The hold comes from the live anchor alone, as set out in the PR body.

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

---

drafted by Claude on behalf of Daniel Stephenson