From 117161e6ff22bafb16666ad2bcecc7b0ac7bc0e3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 26 Nov 2025 17:31:56 +0100
Subject: [PATCH] docs: document heartbeat idle override and tests

---
 CHANGELOG.md               | 1 +
 README.md                  | 3 ++-
 docs/heartbeat.md          | 1 +
 src/web/auto-reply.test.ts | 1 +
 4 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 08e2838f0..2025e714e 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/README.md b/README.md
index f1e0684fc..dcc581694 100644
--- a/README.md
+++ b/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.
diff --git a/docs/heartbeat.md b/docs/heartbeat.md
index d77349598..506b4f321 100644
--- a/docs/heartbeat.md
+++ b/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.
diff --git a/src/web/auto-reply.test.ts b/src/web/auto-reply.test.ts
index 3219d6c62..896c4e70b 100644
--- a/src/web/auto-reply.test.ts
+++ b/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", () => {