fix(heartbeat): frontend-agnostic outbound + comprehensive test coverage

[claudiusthebot]

Problem

PR #150 introduced an outbound-messaging block in the heartbeat system prompt that hard-codes telegram-tools, "Telegram ID", and Telegram-only examples:

OUTBOUND MESSAGING: You also have access to telegram-tools — `send`,
`react`, ...
...
Known chat IDs live in your memory.md (see the Users section — Dylan's
Telegram ID is 352042062 for DM; ...

Talon supports multiple frontends (Telegram, Teams, Terminal, etc) and buildMcpServers already spawns one ${frontend}-tools MCP server per non-terminal frontend — including multiple at once. The hard-coded prompt misleads any heartbeat running on a non-Telegram deployment or a multi-frontend deployment.

The follow-up commit (test(heartbeat-outbound): comprehensive unit + integration coverage) expands test coverage across the whole heartbeat outbound surface — not just the new prompt builder, but the bridge, gateway, and helper layers PR #150 introduced.

What this PR does

Fix (fix(heartbeat): frontend-agnostic outbound-messaging prompt)

1. New getActiveFrontends() in backend/claude-sdk/options.ts — small helper returning the list of non-terminal frontends. Same filter buildMcpServers was running inline; now de-duplicated. Exported via the barrel.

2. New buildHeartbeatSystemPrompt() in core/heartbeat.ts (exported for tests) — builds the prompt dynamically:

   • Zero non-terminal frontends → base prompt only, no OUTBOUND MESSAGING block, no chat_id mention.
   • One or more frontends → lists every ${frontend}-tools server by name, uses the first frontend in the example send(...) call, refers to chat IDs as "per-frontend".
   • Falls back to the base prompt if getActiveFrontends() throws (test paths) — same try/catch pattern PR feat(heartbeat): outbound telegram — explicit chat_id routing #150 used for buildMcpServers.

The hard-coded Telegram chat_id (352042062) is no longer in the prompt. It lives in memory.md anyway.

Test expansion (test(heartbeat-outbound): comprehensive unit + integration coverage)

Total: 29 new test cases across 4 files. 96 tests across the directly-touched surface, all passing.

claude-sdk-options.test.ts (+11 cases)

• getActiveFrontends — 8 cases: scalar terminal/telegram/teams, array combinations, terminal filtering, multi-frontend order preservation, throw propagation.
• buildMcpServers heartbeat-tier — 7 cases including the TALON_CHAT_ID="heartbeat" sentinel path, per-frontend env isolation (no cross-pollination between telegram-tools and teams-tools env), multi-frontend + brave-search combos.

heartbeat.test.ts (+7 cases, from the initial fix commit)

• buildHeartbeatSystemPrompt shape — no frontends → no OUTBOUND MESSAGING, telegram only → references telegram-tools not teams-tools, teams only → references teams-tools not telegram-tools, multi-frontend lists both, first frontend goes into the example send(...), no chat_id mention when no frontends configured, throws-path fallback.

bridge.test.ts (+6 cases)

• Negative numeric chat_id (Telegram supergroup IDs are -100<id> — most common heartbeat target in practice; sign-handling bug would silently misroute).
• chat_id=0 promoted correctly (gateway decides what to do with falsy).
• chat_id=null forwarded as String(null)="null" (defensive — schema validates upstream).
• Heartbeat sentinel default ("heartbeat") MUST be overridden when explicit chat_id supplied — otherwise outbound would silently fail to route.
• Heartbeat sentinel passed through verbatim when no explicit chat_id (gateway's rawChatId !== "heartbeat" guard catches it).
• String chat_id with leading zeros preserved (no Number() coercion).

gateway-http.test.ts (+5 cases)

• Negative chat_id routes without active context (the supergroup case).
• chat_id=0 rejected by !chatId falsy guard.
• Heartbeat sentinel as explicit chat_id rejected — defends against routing-bypass if a heartbeat-tier MCP ever ships the sentinel literally.
• Negative chat_id sign preserved through the handler (defensive against Math.abs / int32 truncation).
• Coexistence: explicit chat_id matching an active context still routes via the explicit-routing branch (no exception, no double-dispatch).

Why these specific edge cases

• Negative chat_id is the most subtle silent-bug surface. Every Telegram supergroup has a negative ID, so heartbeat → group outbound depends on this working. A coercion bug here misroutes silently.
• Heartbeat sentinel guard is the routing-safety net. If rawChatId === "heartbeat" ever stopped triggering the rejection branch, heartbeats could spam unrelated chats.
• getActiveFrontends is the multi-frontend correctness backbone for the new prompt builder.
• Bridge sentinel-override is the path heartbeats actually take in production — explicit chat_id always wins over the spawn-time TALON_CHAT_ID="heartbeat" default.

Verification

• npx vitest run — full suite 1848/1861 pass (1 pre-existing package.functional failure unrelated, 12 skipped live-tier)
• 96 tests across the 4 directly-touched files all pass
• tsc --noEmit clean
• prettier --check clean
• npm run lint — 0 errors, 0 warnings on changed files

Stacking with PR #144

This branches off main (77e7771, post-#150). It does not include PR #144 (heartbeat-eviction). When both land, the second to merge will need a trivial rebase — different sections of heartbeat.ts, no real conflict.

🤖 Generated with Claude Code