Heartbeat session keys stabilized

Summary

• Problem: When isolatedSession: true is set in heartbeat config, each wake-triggered heartbeat tick appends another :heartbeat suffix to the session key, producing keys like agent:main:main:heartbeat:heartbeat:heartbeat:... that grow without bound.
• Why it matters: Session keys grow indefinitely, session store accumulates orphaned entries, and debugging/session management becomes difficult. Eventually hits string length limits.
• What changed: Strip all trailing :heartbeat suffixes before re-appending in resolveIsolatedHeartbeatSessionKey() (regex fix + three-branch resolution logic). Added 9 regression tests covering all key-stability scenarios.
• What did NOT change (scope boundary): No changes to resolveHeartbeatSession(), wake dispatch, or session key parsing. The fix is scoped to the single append site.
• Note: 535 additions, of which 383 are regression tests. Production change is ~56 lines in heartbeat-runner.ts.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59493
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: Feedback loop between heartbeat runner and wake requests. During an isolated heartbeat run, exec/subagent completions call requestHeartbeatNow() with the current session key (already suffixed with :heartbeat). The wake handler passes this key back into runHeartbeatOnce(), which appends :heartbeat again at heartbeat-runner.ts:590 without stripping the existing suffix.
• Missing detection / guardrail: No idempotency guard at the :heartbeat append site. resolveHeartbeatSession() accepts forcedSessionKey without normalizing away existing heartbeat suffixes.
• Prior context: The isolated session feature was added to reduce token cost by giving each heartbeat tick a fresh transcript. The wake-request path (requestHeartbeatNow → wakeHandler → run() → runOnce()) passes sessionKey through without sanitization.
• Why this regressed now: The interaction between isolatedSession: true and wake-triggered re-entry (exec events during heartbeat) was not covered by the original isolated session tests.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/infra/heartbeat-runner.isolated-key-stability.test.ts
• Scenarios the tests lock in (9 total):
  1. Wake path with already-suffixed key → key stays <base>:heartbeat (no double suffix)
  2. Clean base key → appends :heartbeat exactly once
  3. Deeply accumulated key (e.g. base:heartbeat:heartbeat:heartbeat) → converges to <base>:heartbeat in one call
  4. Configured base key that legitimately ends with :heartbeat (e.g. alerts:heartbeat) → gets alerts:heartbeat:heartbeat, not stripped
  5. Wake re-entry for case 4 → key stays stable at alerts:heartbeat:heartbeat
  6. Forced real :heartbeat session (not from isolatedSession config) → gets :heartbeat appended
  7. Wake re-entry for case 6 → stable
  8. Task-based heartbeat skip (no tasks due) → no isolated session created
  9. Legacy isolated key without stored marker (created before heartbeatIsolatedBaseSessionKey was introduced) → converges to canonical <base>:heartbeat without producing <base>:heartbeat:heartbeat
• Why this is the smallest reliable guardrail: Tests exercise runHeartbeatOnce() directly with pre-suffixed session keys, simulating the exact wake-request feedback loop without needing a full gateway or real exec events.

User-visible / Behavior Changes

• Isolated heartbeat sessions now use a stable key <base>:heartbeat across all ticks instead of accumulating suffixes.
• Existing sessions with accumulated suffixes will converge to the stable key on next heartbeat tick.
• Legacy sessions created before the heartbeatIsolatedBaseSessionKey marker was introduced also converge correctly.

Diagram (if applicable)

Before (feedback loop):
  tick 1: base → base:heartbeat (agent runs, exec event fires)
  wake:   requestHeartbeatNow(key="base:heartbeat")
  tick 2: base:heartbeat → base:heartbeat:heartbeat
  wake:   requestHeartbeatNow(key="base:heartbeat:heartbeat")
  tick 3: base:heartbeat:heartbeat → base:heartbeat:heartbeat:heartbeat
  ... (unbounded growth)

After (stable):
  tick 1: base → base:heartbeat (agent runs, exec event fires)
  wake:   requestHeartbeatNow(key="base:heartbeat")
  tick 2: strip trailing :heartbeat(s) → "base", append → base:heartbeat
  wake:   requestHeartbeatNow(key="base:heartbeat")
  tick 3: strip trailing :heartbeat(s) → "base", append → base:heartbeat
  ... (stable)

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux 6.8.0-106-generic (x64), Ubuntu (as reported in issue)
• Runtime/container: Node 22+
• Model/provider: Any (issue is model-agnostic)
• Integration/channel: Any channel with heartbeat
• Relevant config: agents.defaults.heartbeat.isolatedSession: true

Steps

1. Configure agent heartbeat with isolatedSession: true and every: "5m"
2. Restart gateway
3. Wait for 2+ heartbeat ticks (especially with exec tool activity)
4. Run sessions_list and observe session keys

Expected

• All heartbeat sessions use stable key: agent:<agentId>:main:heartbeat

Actual

• Session keys accumulate :heartbeat suffixes on each wake-triggered tick

Evidence

• Failing test/log before + passing after

Test output (9 tests, all passing):

✓ does not accumulate :heartbeat suffix when wake passes an already-suffixed key
✓ appends :heartbeat exactly once from a clean base key
✓ stays stable even with multiply-accumulated suffixes
✓ keeps isolated keys distinct when the configured base key already ends with :heartbeat
✓ stays stable for wake re-entry when the configured base key already ends with :heartbeat
✓ keeps a forced real :heartbeat session distinct from the heartbeat-isolated sibling
✓ stays stable when a forced real :heartbeat session re-enters through its isolated sibling
✓ does not create an isolated session when task-based heartbeat skips for no-tasks-due
✓ converges a legacy isolated key that lacks the stored marker (single :heartbeat suffix)

Full heartbeat test suite: all passing.

Human Verification (required)

• Verified scenarios: Ran all 9 new regression tests + full heartbeat suite, pnpm check (lint/typecheck/format all green)
• Edge cases checked:
  • Deeply accumulated keys (base:heartbeat:heartbeat:heartbeat) correctly converge in one call
  • Clean keys still get :heartbeat appended exactly once
  • Configured base keys legitimately ending with :heartbeat (e.g. alerts:heartbeat) are not incorrectly stripped — they get alerts:heartbeat:heartbeat as expected and stay stable
  • Legacy isolated sessions lacking the stored heartbeatIsolatedBaseSessionKey marker converge correctly without double-suffix regression
  • Task-based skip (no tasks due) leaves no isolated session in the store
  • Non-isolated heartbeats are unaffected
• What I did not verify: Live gateway with real exec events triggering wake requests (no access to a running gateway with isolatedSession: true)

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No — existing accumulated keys auto-converge on next tick; legacy sessions without stored marker also converge

Risks and Mitigations

• Risk: Regex (:heartbeat)+$ could theoretically match a user-chosen session key that legitimately ends with :heartbeat.
  • Mitigation: The strip only runs inside the useIsolatedSession branch, which already knows the key will get :heartbeat appended. The resolution logic has three branches: (1) stored heartbeatIsolatedBaseSessionKey marker takes priority; (2) suffix-strip applies only when the configured base does NOT itself end with :heartbeat; (3) fallback passes through. This means alerts:heartbeat as a configured session name correctly produces alerts:heartbeat:heartbeat (branch 3 fallback) rather than being erroneously stripped — confirmed by tests 4 and 5.