fix(flights): a deferred tile is not a failed one

[ChuckBuilds]

Follow-up to #284, which is now merged. Rebuilt on top of main so this is only the fix.

The bug

#284 moved tile fetching off the render thread — the right idea — so the render path now asks for tiles that aren't cached yet and gets None back. But the compositing loop counts those the same as a tile the server refused to serve, and the failure branch disables the map background for the rest of the session above 50%.

On a cold cache every tile is a deferral. Reproduced against the merged code, 110-tile grid:

FRAME 1  cold cache:                  returned=None   map_bg_enabled=True
FRAME 2  prefetch delivered 10/110:   returned=None   map_bg_enabled=False
FRAME 3  ALL 110 tiles cached:        returned=None   map_bg_enabled=False

Below the 50% bar it fails the other way — the partial composite is cached under a key of (centre, zoom, size), all static config, so the invalidation can never fire:

FRAME 2  60/110 present (45% missing): image returned, 46.8% black  -> cached
FRAME 3  ALL 110 tiles cached:         46.8% black, 0 tiles re-read
         identical object to frame 2:  True

Either way the map is gone for the session and only a config reload clears it. Before #284 this was unreachable: the render thread fetched inline, so a healthy server meant a 0% failure rate. The queue is only populated by a render, so every cold start goes through this — not an edge case.

The fix

• Deferrals counted separately from failures. Only a genuine fetch failure (allow_network=True) counts toward the disable threshold, so the safety valve still fires for a server that really is refusing.
• A composite with any tile missing is not cached. Costs one recomposition per frame from already-cached tiles until the prefetch catches up, then nothing.
• _MAX_TILES_WANTED 64 → 256. The grid reaches 16×16 (max_tiles = 16 is applied per axis, despite the # 4x4 maximum comment beside it) and a default config already needs 110, so the render path could never queue a whole map in one pass — which kept frames partial long enough to trip the two bugs above.
• Prefetch bounded at 10s per cycle, remainder returned to the queue. It previously drained the whole queue at _TILE_TIMEOUT_SECONDS = 3 each against PluginExecutor's 30s budget for the entire update, so a slow-but-succeeding server could overrun it and be recorded as a failed update. The existing cooldown only rescues a server that fails outright, not one that's merely slow.

Testing

New test_map_cold_start.py drives the real _get_map_background through a startup sequence. The existing test asserts by AST that display() passes allow_network=False — true, and never the problem; it never executes the function where the bug lives.

It follows the LEDMATRIX_CORE skip convention the sibling tests use, so it imports and exercises the real FlightTrackerPlugin (including the read-only display_width/display_height properties) rather than compiling methods out of the file.

Mutation-checked: 6 of its 8 checks fail against main. The 2 that pass are the behaviours deliberately preserved — the failure valve, and that a complete map is still cached.

Full flights suite passes: test_config_reload, test_map_cold_start, test_no_disk_write_on_poll, test_overhead_radius, test_tile_network_bound, test_tiles_off_render_thread, test_vegas_map_parity.

Manifest 1.12.10 → 1.12.11, plugins.json regenerated by the pre-commit hook.

Scope note

A total fetch failure returns earlier, at tiles_fetched == 0, without disabling anything. That predates #284 and is covered by the fetch cooldown, so I left it rather than widen the change — my first draft of the test assumed otherwise and caught me.

🤖 Generated with Claude Code

https://claude.ai/code/session_01STMbQE4YctTacQXfbYqKuW

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b5e01c87-bd1a-4f49-afbb-22af888c557f

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 13 complexity

Metric	Results
Complexity	13

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}