docs: document heartbeat idle override and tests

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Web relay now supports configurable command heartbeats (`inbound.reply.heartbeatMinutes`, default 30m) that ping Claude with a `HEARTBEAT_OK` sentinel; outbound messages are skipped when the token is returned, and normal/verbose logs record each heartbeat tick.
 - New `warelay heartbeat` CLI triggers a one-off heartbeat (web provider, auto-detects logged-in session; optional `--to` override). Relay gains `--heartbeat-now` to fire an immediate heartbeat on startup.
 - Added `warelay relay:tmux:heartbeat` helper to start relay in tmux and emit a startup heartbeat automatically.
+- Heartbeat session handling now supports `inbound.reply.session.heartbeatIdleMinutes` and does not refresh `updatedAt` on skipped heartbeats, so sessions still expire on idle.
 
 ## 1.1.0 — 2025-11-26
 

README.md

@@ -123,7 +123,8 @@ Best practice: use a dedicated WhatsApp account (separate SIM/eSIM or business a
 #### Heartbeat pings (command mode)
 - When `heartbeatMinutes` is set (default 30 for `mode: "command"`), the relay periodically runs your command/Claude session with a heartbeat prompt.
 - If Claude replies exactly `HEARTBEAT_OK`, the message is suppressed; otherwise the reply (or media) is forwarded. Suppressions are still logged so you know the heartbeat ran.
-- Trigger one manually with `warelay heartbeat` (web provider only). Use `--heartbeat-now` to fire once at relay start.
+- Override session freshness for heartbeats with `session.heartbeatIdleMinutes` (defaults to `session.idleMinutes`). Heartbeat skips do **not** bump `updatedAt`, so sessions still expire normally.
+- Trigger one manually with `warelay heartbeat` (web provider only, `--verbose` prints session info). Use `--heartbeat-now` to fire once at relay start.
 
 ### Logging (optional)
 - File logs are written to `/tmp/warelay/warelay.log` by default. Levels: `silent | fatal | error | warn | info | debug | trace` (CLI `--verbose` forces `debug`). Web-provider inbound/outbound entries include message bodies and auto-reply text for easier auditing.

docs/heartbeat.md

@@ -9,6 +9,7 @@ Goal: add a simple heartbeat poll for command-based auto-replies (Claude-driven)
 ## Config & defaults
 - New config key: `inbound.reply.heartbeatMinutes` (number of minutes; `0` or undefined disables).
 - Default: 30 minutes when a command-mode reply is configured.
+- New optional idle override for heartbeats: `inbound.reply.session.heartbeatIdleMinutes` (defaults to `idleMinutes`). Heartbeat skips do **not** update the session `updatedAt` so idle expiry still works.
 
 ## Poller behavior
 - When relay runs with command-mode auto-reply, start a timer with the resolved heartbeat interval.

src/web/auto-reply.test.ts

@@ -20,6 +20,7 @@ import {
   resetLoadConfigMock,
   setLoadConfigMock,
 } from "./test-helpers.js";
+import { resolveStorePath } from "../config/sessions.js";
 
 describe("heartbeat helpers", () => {
   it("strips heartbeat token and skips when only token", () => {