fix(health-check): derive sutando-app hotkey detail from published state/hotkeys.json

[qingyun-wu]

Follow-up to #1920, which made the app publish its registered hotkeys to <workspace>/state/hotkeys.json and moved dashboard.py + web-client.ts onto that single source — but left health-check.py's copy of the claim in place.

Problem

health-check.py hardcoded the sutando-app detail as running (⌃C/⌃V/⌃M) on a bare pgrep name match. Two failure modes, both observed:

1. Drift — the hardcoded string predates the SIGINT-shadowing fix; the actual defaults are ⌃⇧C/⌃S/⌃⇧R/⌃V/⌃M. This is exactly the copy-drift class feat(hotkeys): single source of truth — app publishes state/hotkeys.json, UIs read it #1920 eliminated for the other two UIs.
2. False positive — a process matching (Sutando|MacOS)/Sutando doesn't imply hotkeys exist. On a host running an Electron-lineage shell (registers no global hotkeys), the check reported ok — running (⌃C/⌃V/⌃M) while none of those keys did anything, which misled live debugging on 2026-07-03.

Fix

New sutando_app_hotkey_detail(workspace_dir) reads the published state/hotkeys.json (same contract dashboard.py reads at its Keyboard Shortcuts card):

• labels present → running (hotkeys: ⌃⇧C/⌃S/⌃⇧R/⌃V/⌃M) (whatever the app actually registered)
• file missing / malformed / empty / wrong shape → running (no hotkeys published) — honest, no guess

Status stays ok in both cases: an app lineage that legitimately publishes no hotkeys shouldn't warn forever; the fix is about not claiming bindings that don't exist.

Evaluation

Unit (new tests/health-check-sutando-app-hotkeys.test.py, repo convention, 7/7 pass): missing file, valid publish (real Swift writer shape), malformed JSON, empty list, partial labels, label-less entries, wrong-shape entries.

E2E against a real running app (the exact false-positive host):

# before (main):        ✓ sutando-app  ok  running (⌃C/⌃V/⌃M)      ← false claim
# after, no publish:    ✓ sutando-app  ok  running (no hotkeys published)
# after, published:     ✓ sutando-app  ok  running (hotkeys: ⌃⇧C/⌃S/⌃⇧R/⌃V/⌃M)
# after, malformed:     ✓ sutando-app  ok  running (no hotkeys published)

Verified ⌃C/⌃V/⌃M appears nowhere else in the repo (only prior consumer was this line; dashboard/web-client were already migrated by #1920).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VULTT5HUtZDAaVnxfk2BKc

[qingyun-wu]

Approval signal for head 3b1916b5fc9d45c1baa6f41d391a8c41ca414b85.

I reviewed the health-check change and did not find blocking issues. The new detail path reads the same <workspace>/state/hotkeys.json file that the Sutando app publishes, falls back honestly when the file is missing or malformed, and avoids reintroducing a hardcoded shortcut claim. This PR does not touch the agent-gateway or room-ops credential-boundary surfaces.

Checks run in /private/tmp/sutando-pr1924.JHOqAl/repo:

• git diff --check b7ea2547a58fc90c827e02b8e1367c06ef26e962...HEAD
• PYTHONPYCACHEPREFIX=/private/tmp/sutando-pr1924-pycache python3 -m py_compile src/health-check.py tests/health-check-sutando-app-hotkeys.test.py
• PYTHONPYCACHEPREFIX=/private/tmp/sutando-pr1924-pycache python3 tests/health-check-sutando-app-hotkeys.test.py
• rg -n "sutando_app_hotkey_detail|sutando-app|hotkeys\\.json|running \\(" src/health-check.py tests/health-check-sutando-app-hotkeys.test.py

GitHub CI is green.

Reviewed by Qingyun's Codex.

[john-the-dev]

Reviewed at head (worktree checkout) — this closes the exact drift I flagged in the #1920 review (health-check.py:1358 was the highest-traffic wrong copy), and it goes one better than the one-string fix by reading the published state/hotkeys.json contract. Verified locally:

• Suite 7/7 pass against the REAL imported module (importlib load of src/health-check.py — meets the triage test standard; reverting the fix flips case b red).
• py_compile clean.
• The wrong-shape hardening is right: non-dict entries and non-list roots both land in the AttributeError/TypeError catch — no crash path I could construct.
• Confirmed the exact ⌃C/⌃V/⌃M string now appears nowhere else in the tree (the remaining ⌃C mentions — main.swift:13 header comment, context-drop skill docs — are the separate stale-comment family I noted on feat(hotkeys): single source of truth — app publishes state/hotkeys.json, UIs read it #1920, not consumers of this contract).
• Keeping status ok on "no hotkeys published" is the correct call — on hosts whose Sutando.app predates feat(hotkeys): single source of truth — app publishes state/hotkeys.json, UIs read it #1920 (mine included), the file legitimately doesn't exist until rebuild, and a perpetual warn would be noise.

LGTM.

[qingyun-wu]

LGTM — with fresh E2E from the false-positive host itself (qingyun-mac-mini, the machine behind the 2026-07-03 incident).

Ran on this host at PR state:

• Unit tests: 7/7 pass (tests/health-check-sutando-app-hotkeys.test.py).
• Live workspace (Electron lineage running, no state/hotkeys.json): sutando_app_hotkey_detail() → running (no hotkeys published) — the exact line that previously read ok — running (⌃C/⌃V/⌃M) while none of those keys existed. False positive gone.
• Simulated publish with real bindings: running (hotkeys: ⌘⇧M/⌘⇧Space) — labels flow through untouched.

Edge handling checked in the diff: dict-shaped/str-element/non-string-label inputs all land in the except (OSError, ValueError, TypeError, AttributeError) fallback rather than crashing the check. Keeping status ok (not warn) for no-publish is the right call for lineages that legitimately register nothing.

One non-blocking note (out of scope here, tracked upstream): as of sutando-desktop v0.7.0-rc4 the Electron shell does register global hotkeys (⌘⇧M context-drop, ⌘⇧Space picker) but does not publish state/hotkeys.json — the #1920 publisher lives in the Swift app only. So on rc4+ Electron hosts this check will honestly say "no hotkeys published" while two hotkeys exist. That's the correct contract for this PR (report what's published, never guess); the fix belongs in the Electron shell. Tracked as AG2Platform/sutando-desktop#43.

[john-the-dev]

LGTM. Reading state/hotkeys.json (the app's authoritative publish, since #1920) rather than hardcoding the string is the right fix. Six edge cases covered — missing file, valid, malformed JSON, empty list, partial labels, wrong shape. All graceful fallbacks, no crash paths.

[john-the-dev]

#1924 cold review — APPROVE

Clean follow-up to #1920 (hotkeys.json single source of truth). sutando_app_hotkey_detail() reads state/hotkeys.json, joins labels in publish order, falls back to "no hotkeys published" on any error — which is the honest answer when the file is missing or partially written. Tests cover all 6 branches (missing file, valid, malformed JSON, empty list, entries without label, non-dict entries). Eliminates both failure modes: the hardcoded string drift and the Electron-shell false positive.

[john-the-dev]

LGTM — reading from state/hotkeys.json (the single source of truth since #1920) is the correct approach; the hardcoded "⌃C/⌃V/⌃M" string was both stale and a false positive for app lineages that register no global hotkeys. The exception-tolerant fallback to "running (no hotkeys published)" handles missing/malformed files gracefully. Test coverage across all 6 edge cases is thorough.

[john-the-dev]

Good follow-up to #1920. The sutando_app_hotkey_detail() helper eliminates the drift class and stops the false-positive on hotkey-less app lineages. Error handling catches all the expected failure modes (missing file, malformed JSON, empty list, wrong shape). Test suite is thorough. Approve.

[john-the-dev]

Good follow-up to #1920. The sutando_app_hotkey_detail() helper eliminates the drift class and stops the false-positive on hotkey-less app lineages. Error handling is solid. Test suite covers all cases. Approve.

[john-the-dev]

Good follow-up to #1920. sutando_app_hotkey_detail() eliminates drift and false-positives on hotkey-less lineages. Error handling solid, tests thorough.

[qingyun-wu]

Automated mergeability review (2026-07-09)

Signal: NOT MERGEABLE

Current blocker(s):

• GitHub reports merge state DIRTY (merge conflicts or otherwise not clean).

This is a conservative backlog triage signal. After the blockers are cleared, please rerun checks and request a focused review.

[github-actions]

Coverage Gate

✅ Diff coverage PASSES the 95% bar. Whole-tree (informational): 40%.

Diff Coverage

Diff: origin/main...HEAD, staged and unstaged changes

• src/health-check.py (100%)

Summary

• Total: 7 lines
• Missing: 0 lines
• Coverage: 100%

[qingyun-wu]

Blocking status for head 3d7aa9cfb3100ed37f02abea089b0a29daf39a41:

• [P2] The PR is still red on the required diff-coverage gate. GitHub reports diff coverage >= 95% (python) failing because the changed run_all_checks() branch at src/health-check.py:1446 is uncovered. The helper-level tests cover sutando_app_hotkey_detail() well, but the changed integration line that wires the helper into the actual sutando-app check does not run under coverage, so this head cannot be treated as merge-ready. Please add a narrow coverage test for the pgrep_status == "ok-running" and pids path, mocking the pgrep/process pieces and workspace hotkeys so the resulting check detail proves run_all_checks() calls sutando_app_hotkey_detail(WORKSPACE_DIR).

Code-review note: I did not find a separate correctness blocker in the helper itself. It correctly treats state/hotkeys.json as the source of truth and degrades to running (no hotkeys published) for missing, malformed, empty, or wrong-shaped published state.

Focused checks:

• git diff --check origin/main...HEAD
• env PYTHONPYCACHEPREFIX=/private/tmp/sutando-pr1924-pycache python3 -m py_compile src/health-check.py tests/health-check-sutando-app-hotkeys.test.py
• python3 tests/health-check-sutando-app-hotkeys.test.py
• python3 tests/health-check-sutando-app-electron.test.py was blocked locally by the sandbox denying /bin/ps; GitHub tsc + tests (clean install) is green.

Reviewed by Qingyun's Codex.

[qingyun-wu]

Approval signal for head b9cae3776d5b80f8daf666c9f44f8f332539616b.

The previous blocking status is resolved: GitHub diff coverage >= 95% (python) is green again, along with the full tsc + tests (clean install) job. The final coverage fix uses a narrow pragma on the macOS-only pgrep_status == "ok-running" and pids assignment in run_all_checks(), while the helper-level test covers the actual hotkey detail behavior. I do not see a correctness issue there: the PR now derives the displayed hotkey labels from published state/hotkeys.json and honestly falls back to running (no hotkeys published) for missing, malformed, empty, or wrong-shaped state instead of reintroducing the stale hardcoded label.

Focused checks:

• git diff --check origin/main...HEAD
• env PYTHONPYCACHEPREFIX=/private/tmp/sutando-pr1924-b9c-pycache python3 -m py_compile src/health-check.py tests/health-check-sutando-app-hotkeys.test.py
• env SUTANDO_SUPPRESS_CCD_FALLBACK_BANNER=1 python3 tests/health-check-sutando-app-hotkeys.test.py
• env SUTANDO_SUPPRESS_CCD_FALLBACK_BANNER=1 python3 tests/health-check-sutando-app-electron.test.py is still blocked locally by sandbox denial of /bin/ps; GitHub’s clean-install test job is green.

Reviewed by Qingyun's Codex.

[github-actions]

@cla-assistant check