fix(stage): tolerate a corrupted cache/last_coords.txt at startup

[Alpaca233]

Problem

squid.stage.utils.get_cached_position() only caught RuntimeError, which neither float() nor tuple unpacking ever raise. So if cache/last_coords.txt was corrupted — truncated by a crash mid-write, edited by hand, filled with garbage/binary — a ValueError (or UnicodeDecodeError) escaped straight out of HighContentScreeningGui.__init__ and the software would not start until someone deleted the file manually.

Fix

Read side — treat an unreadable or unparseable cache file exactly like a missing one: log a WARNING and return None, so the GUI falls through to its existing "no cached position" path (Z moves to the safety position) and startup continues. "Could not read the file" and "could not parse it" are reported separately, so a permission problem isn't described as corruption. Non-finite values (nan/inf) are rejected too, since cache_position() validates against the axis limits and can never write them. The read is capped at 4096 bytes so a stray large file at that path can't be pulled into memory during startup.

Write side — cache_position() truncated the cache in place before writing, which is what produces the partial files the read side now has to tolerate. It writes to a temp file and os.replace()s it into place instead, so an interrupted write leaves the last good position intact. This matches the existing pattern in control/channel_sequence.py.

A corrupt file is intentionally left in place rather than deleted; it is overwritten on the next clean exit, and the repeating warning is the right signal if the machine never exits cleanly.

Scope note

get_cached_position() deliberately does not range-check a well-formed but stale position against the axis limits, and its docstring says so. A stale finite out-of-range X/Y would still cause a move timeout at startup; sharing the validation between the read and write sides needs stage_config threaded into the reader and is left as a follow-up.

Also out of scope, found while reviewing this: control/_def.py (two readers, at import time), control/widgets.py:get_last_used_saving_path(), and several other cache/ readers have the same crash-on-corrupt-file shape with five different except tuples between them. A shared tolerant-read/atomic-write helper would make this structural rather than per-author, but it touches 6+ files and doesn't belong in a targeted fix.

Tests

tests/squid/test_stage.py: corruption cases parametrized over bytes — garbage, too few / too many fields, a bad field, empty, nan, inf, and undecodable bytes — each asserting None is returned and a warning names the cache file; plus a test pinning the contents preview in the warning, and one covering an interrupted write (the previously-cached position must survive). Both behaviors were confirmed failing before the code changed.

python3 -m pytest tests/squid/test_stage.py tests/squid/test_stage_z_limit.py
48 passed, 1 skipped

Black clean at 120 columns.

End-to-end check

Planted this is not,a valid\x00position in the cache and launched main_hcs.py --simulation:

WARNING - Cached position file 'cache/last_coords.txt' is corrupted (could not convert string to float: 'this is not'), contents='this is not,a valid\x00position'. Continuing as if there is no cached position.
INFO - Cache position is not exists.  Moving Z axis to safety position (gui_hcs.py:788)

Startup proceeded normally with no traceback. Round-tripping a position after the atomic-write change leaves no .tmp debris behind.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Improves stage startup resilience by safely handling corrupt cached positions and atomically updating the cache.

Changes:

• Treats unreadable, malformed, and non-finite cached coordinates as missing.
• Uses atomic replacement to preserve the previous cache after failed writes.
• Adds corruption and interrupted-write tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
software/squid/stage/utils.py	Adds tolerant cache reads and atomic writes.
software/tests/squid/test_stage.py	Tests missing/corrupt caches and failed writes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Alpaca233]

Good catch — confirmed and fixed in 5866bb0.

Reproduced it first: a 4118-byte file consisting of 11.0,22.0,1.0 plus whitespace padding to exactly 4096 chars followed by garbage returned Pos(x_mm=11.0, y_mm=22.0, z_mm=1.0), so the stage would have moved to a position parsed from a prefix of a file we never validated — the exact failure mode this series is meant to prevent.

Now reads _MAX_CACHE_BYTES + 1 and rejects anything longer before parsing, so the cap is an assertion about the format ("a valid cache is one short line") rather than a silent truncation. The oversized file funnels into the same "is corrupted" warning path:

WARNING - Cached position file '...' is corrupted (file is larger than 4096 bytes), contents='11.0,22.0,1.0'. Continuing as if there is no cached position.

Added a test for it (padding derived from the constant so it can't drift), plus a regression guard that a second coordinate line is rejected too — that one already passed, since the extra fields fail the 3-tuple unpack.