Context
PR #2191 wholesale-restored src/infra/heartbeat-runner.ts from pre-v2026.3.1. This discarded significant heartbeat protocol improvements from v2026.3.1 that are NOT tied to gutted subsystems. The heartbeat runner is core RemoteClaw middleware infrastructure.
Audit report: hq/engineering/notes/post-remediation-audit-b3b4.md
Findings
1. ackMaxChars configuration
New config path for maximum characters in heartbeat acknowledgment responses. Prevents overly verbose heartbeat acks from flooding channels.
2. HEARTBEAT.md file gating
When HEARTBEAT.md exists but is effectively empty (isHeartbeatContentEffectivelyEmpty), skip heartbeat execution. BUT exec/cron/wake events bypass this gate (they always run). Has proper ENOENT handling (missing file = continue normally).
3. HEARTBEAT_TOKEN structured protocol
Heartbeat OK uses a structured token (HEARTBEAT_TOKEN) instead of raw text summary. Paired with stripHeartbeatToken for extracting the token from agent responses. Replaces the old heartbeatReport tool-based normalization.
4. buildOutboundSessionContext
Session-aware outbound delivery. Heartbeat outbound messages now include session context, enabling proper session tracking for heartbeat-originated messages.
5. Exec fallback text
Better handling of exec-completion heartbeats with fallback text when the agent doesn't produce a meaningful response.
6. HeartbeatSkipReason type
Typed skip reasons for more specific heartbeat skip reporting (not just "skipped" but why).
Complexity Note
Several of these improvements are intertwined with the stripHeartbeatToken and HEARTBEAT_TOKEN infrastructure. Evaluate compatibility with RemoteClaw's ChannelBridge-based architecture. The improvements should work with ChannelBridge since they operate at the heartbeat runner level (above the dispatch layer).
See also #2194 (heartbeat file-based prompt resolution) which is related but addresses a different aspect.
Exit Criterion
Heartbeat runner supports ackMaxChars, HEARTBEAT.md gating, and structured token protocol. Existing heartbeat tests pass.
Context
PR #2191 wholesale-restored
src/infra/heartbeat-runner.tsfrom pre-v2026.3.1. This discarded significant heartbeat protocol improvements from v2026.3.1 that are NOT tied to gutted subsystems. The heartbeat runner is core RemoteClaw middleware infrastructure.Audit report:
hq/engineering/notes/post-remediation-audit-b3b4.mdFindings
1.
ackMaxCharsconfigurationNew config path for maximum characters in heartbeat acknowledgment responses. Prevents overly verbose heartbeat acks from flooding channels.
2. HEARTBEAT.md file gating
When HEARTBEAT.md exists but is effectively empty (
isHeartbeatContentEffectivelyEmpty), skip heartbeat execution. BUT exec/cron/wake events bypass this gate (they always run). Has proper ENOENT handling (missing file = continue normally).3.
HEARTBEAT_TOKENstructured protocolHeartbeat OK uses a structured token (
HEARTBEAT_TOKEN) instead of raw text summary. Paired withstripHeartbeatTokenfor extracting the token from agent responses. Replaces the oldheartbeatReporttool-based normalization.4.
buildOutboundSessionContextSession-aware outbound delivery. Heartbeat outbound messages now include session context, enabling proper session tracking for heartbeat-originated messages.
5. Exec fallback text
Better handling of exec-completion heartbeats with fallback text when the agent doesn't produce a meaningful response.
6.
HeartbeatSkipReasontypeTyped skip reasons for more specific heartbeat skip reporting (not just "skipped" but why).
Complexity Note
Several of these improvements are intertwined with the
stripHeartbeatTokenandHEARTBEAT_TOKENinfrastructure. Evaluate compatibility with RemoteClaw's ChannelBridge-based architecture. The improvements should work with ChannelBridge since they operate at the heartbeat runner level (above the dispatch layer).See also #2194 (heartbeat file-based prompt resolution) which is related but addresses a different aspect.
Exit Criterion
Heartbeat runner supports
ackMaxChars, HEARTBEAT.md gating, and structured token protocol. Existing heartbeat tests pass.