fix(monitoring): prefer readable labels over source fingerprints

[camy-x]

Summary

Prevent opaque h:, k:, and m: usage identities from becoming the primary label in Realtime Monitoring when readable metadata is available.
Keep the opaque value available for diagnostics and as the final fallback without changing persisted data or grouping identities.

Scope

• Frontend panel
• Manager Server
• CPA panel mode
• Full Docker mode
• Native packages / release
• Docs / Wiki
• CI / build / tooling

Changes

• Exclude opaque usage identities from readable source and account candidates.
• Prefer an existing host, configured label, account, or API key alias before the internal fingerprint.
• Retain the opaque identity in the diagnostic title and as the final fallback.
• Add regression coverage for both alias promotion and fingerprint-only fallback.

User Impact

Realtime Monitoring again shows a readable caller identity for affected v1.12.13 events instead of k: when an API key alias or other readable metadata is available.

Compatibility / Runtime Notes

• CPA panel mode: The shared realtime frontend display uses the corrected precedence.
• Manager Server mode: Frontend-only behavior change; server persistence remains unchanged.
• Full Docker / native packages: The bundled frontend receives the same display fix; no configuration change is required.

Data / Security Notes

No raw usage data, source hashes, API key hashes, or persistence behavior changes. Opaque source identities remain available in the diagnostic title and grouping identity. Only an already-sanitized configured alias can be promoted.

Risk / Rollback

Risk level: Low

Rollback notes: Revert commit 6db096a.

Verification

• Type check
• Lint
• Tests
• Build
• Manual UI check
• Docs/link check
• Not applicable, docs-only

Commands / evidence:

tsc --noEmit
eslint src/features/monitoring/realtimeSourceDisplay.ts src/features/monitoring/realtimeSourceDisplay.test.ts --report-unused-disable-directives
vitest run src/features/monitoring/realtimeSourceDisplay.test.ts src/features/monitoring/model/eventRows.test.ts src/features/monitoring/components/RealtimeEventsPanel.test.tsx
vitest run src

Focused result: 39 tests passed. Full web result: 225 test files and 3,454 tests passed.

Build and manual UI checks were not run; type checking and full automated frontend coverage passed.

Screenshots / Recordings

N/A — the affected persisted event shape is covered by the regression test and no live deployment containing that event was available locally.

Docs

• README / README_CN updated for user-visible capabilities
• Matching docs manual and navigation updated
• Demo fixtures, screenshots, and deep links reviewed
• Release notes needed
• Not needed — explanation included below

Docs decision: This restores the documented Source / API Key display precedence and does not add a capability or configuration option.

Related

Fixes #781

[seakee]

Thanks for the fix and the investigation.

After further investigation, we confirmed that #781 was caused by the web-side handling of the new h:<sha256> source identity, not only by Realtime Monitoring label precedence.

The complete fix is now covered by #789, including:

• canonical h:<sha256> source normalization
• config candidate mapping and source resolution
• source identity continuity
• monitoring presentation fallback for opaque identities

The presentation fallback introduced here is useful and has been incorporated into the complete fix, but this PR alone does not resolve the underlying source identity regression.

Closing this PR as superseded by #789. Thanks again for the contribution.