# v8.5 Active Session Observer + Heartbeat Thresholds Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add lightweight active-session observation on heartbeat events so Engram can proactively flush/extract when high-risk context growth is detected.

**Architecture:** Introduce a heartbeat observer that tracks per-session growth deltas and triggers bounded observation pipelines before compaction/risk windows. Keep I/O cheap and debounced.

**Tech Stack:** TypeScript, `src/index.ts`, `src/orchestrator.ts`, `src/transcript.ts`, node:test.

---

## Requirements

1. Track per-session byte/token growth since last observer cursor.
2. Configurable thresholds by session size bands.
3. Debounced trigger path to avoid hot-loop churn.
4. No blocking behavior on agent critical path.

## Task 1: Observer cursor state manager

**Files:**
- Create: `src/session-observer-state.ts`
- Test: `tests/session-observer-state.test.ts`

## Task 2: Heartbeat trigger pipeline

**Files:**
- Modify: `src/index.ts`
- Modify: `src/orchestrator.ts`
- Test: `tests/heartbeat-observe-trigger.test.ts`

## Task 3: Config surface + docs

**Files:**
- Modify: `src/types.ts`
- Modify: `src/config.ts`
- Modify: `openclaw.plugin.json`
- Modify: `docs/config-reference.md`

