fix(ui-tui): widget-grid hardening — review fast-follow for #20379

[OutThisLife]

Fast-follow to #20379 (now merged), addressing every finding from the deep review.

Finding 1 (High) — MCP revision acked without being loaded

reload.mcp is now a revision-aware handshake on both sides:

• Client (useConfigSync.ts): syncMcpReload() sends the observed mcp_rev with the request and advances its accepted revision only when the server answers status: reloaded — to the server-reported loaded_rev, falling back to the requested rev on older gateways. The comparison runs on every poll tick (decoupled from mtime), so a reload that failed against a temporarily broken server retries on the next tick instead of being lost until an unrelated MCP edit. An in-flight guard stops the 5 s poll from stacking requests behind a slow reload.
• Server (tui_gateway/server.py): the leader re-hashes the MCP-relevant config after discovery and repeats until the hash is stable (bounded at 3 passes), then records _mcp_reload_loaded_rev. A follower coalesces only when the revision it was asked to load matches what the leader actually loaded — the A-then-B race from the review now makes the B follower re-run the full reload instead of acking B against A's registry. Responses carry loaded_rev.

Tests: tests/tui_gateway/test_mcp_reload_rev.py covers the exact failure sequences deterministically (instrumented lock for thread ordering, no sleeps): failed reload → error + no generation advance; A-then-B overlap → follower re-runs; matching rev → coalesces; failed leader → follower re-runs; legacy no-rev callers keep generation-only coalescing. Client side: 6 vitest cases on the ack/retry/in-flight contract.

Finding 2 (High) — boot theme cache could pin the terminal indefinitely

The cache now has provenance:

• seedBootEnvironment() (extracted, testable against a passed env) records what it seeded. When the current terminal answers OSC-11 with the distrusted #000000 fingerprint, the gateway handler calls invalidateBootBackground(): the slot clears only while it still holds the seeded value, OSC-10 gets first claim in the same startup batch, and a short settle pass re-derives from the live fallback chain. The review's stale-light-cache + pure-black-terminal sequence now lands on dark, and the macOS appearance fallback is no longer suppressed by a stale hint.
• The cache is pin-coherent: commitTheme persists the display.tui_theme pin alongside the resolved theme and physical background, and boot replays it. /theme light on a dark terminal no longer flashes light → dark → light across restarts. The seeded pin counts as config-owned (bootSeededPin), so a later auto can still clear it instead of mistaking it for a user shell export.

Tests (themeBoot.test.ts) cover the review's sequences: stale-light vs current-dark, stale-dark vs ambiguous-light, pinned light on dark background across restart (and the inverse), trusted-overwrite protection, explicit-signal guards.

Finding 3 (Medium) — stacked dialog didn't receive input

Input routing now follows visual stacking: the dialog/grid dispatch is extracted into handleStackedModalInput() with the dialog branch first. Tests drive the real dispatch against the overlay store — each advertised close key (Esc/q/Enter/Ctrl+C) closes only the dialog with the grid byte-identical underneath, grid keys don't leak through while the dialog is up, and routing returns to the grid after it closes.

Finding 4 (Medium) — npm run visual portability (zero new deps)

• The script is now a plain Node launcher (scripts/visual/run.mjs) that sets FORCE_COLOR/COLORTERM itself and spawns tsx via require.resolve('tsx/cli') — no POSIX shell env assignments, and no cross-env dependency needed.
• Output paths derive from os.tmpdir()/hermes-tui-visual via a shared paths.mjs (override with HERMES_TUI_VISUAL_DIR) — no more drive-root /tmp writes on native Windows.
• electron is resolved explicitly from the install tree the desktop workspace already provides (require('electron') in plain Node returns the binary path), with an ELECTRON_BIN override and a clear error pointing at the repo-root install when absent — the review's "invoked through the workspace that owns it" option, instead of declaring a second ~100MB dependency on the TUI workspace for a dev-only harness. package-lock.json is untouched.
• The trailing-whitespace line in render.tsx that git diff --check flags is fixed.

Verified end-to-end: render writes the HTML scene sheet, the electron step produces the screenshot from the tmpdir path, and the missing-electron error path prints the guidance message.

Finding 5 (Perf) — permanent shimmer repaint loop

All shimmer compositions now share one module-level clock: a single interval regardless of how many skeletons are mounted, updates delivered in one timer callback (React batches them into one render pass), interval torn down with the last subscriber. Each mount's animation is bounded (SHIMMER_ANIMATE_MS, 30 s) — after the budget the skeleton freezes in place instead of repainting an idle TUI forever. Fake-timer tests cover single-timer sharing, teardown with the last unsubscribe, and clean restart.

Product note from the review (not changed here)

/grid-test and /dialog-test remain in the production registry for the TUI alpha — flagging that this is now an explicit decision rather than a leftover. Happy to gate them behind a debug flag in a follow-up if preferred.

Verification

• ui-tui: typecheck, eslint, and the full vitest suite green (121 files, 1312 tests).
• Python: scripts/run_tests.sh tests/tui_gateway/ green (37 files, 401 tests), including the new test_mcp_reload_rev.py.
• npm run visual exercised end-to-end on macOS.

[github-actions]

૮ >ﻌ< ა ci review

_{running on 5c714be}

⚠️ Warnings

CI timings · View job

Wall time 10m8s vs 7m58s (+27.2%). 4 job(s) slower, 14 faster, 2 unchanged.

• Build&Test Docker image / build (arm64, ubuntu-24.04-arm, linux/arm64, type=gha,scope=docker-arm64, type=gha,mode=max,scope...: +171.0s
• Build&Test Docker image / build (amd64, ubuntu-latest, linux/amd64, type=gha,scope=docker-amd64, type=gha,mode=max,scope=do...: +147.0s
• Python tests / Run tests slice 3/8: -44.0s
• Python tests / Run tests slice 2/8: -34.0s
• Python tests / Run tests slice 4/8: -24.0s