feat(server): SSE heartbeat on streaming path (#47) (#49)

* docs(spec): design for #47 SSE heartbeat on streaming path

Draft spec for an opt-in idle-watchdog SSE heartbeat covering both
pre-first-byte and mid-stream silent windows. Default disabled,
controlled by CLAUDE_HEARTBEAT_INTERVAL. Targets ~40 LOC.

Decisions captured: D1 whole-stream reset-on-byte; D2 SSE comment
frame; D3 default disabled; D4 relocate ensureHeaders() to post-spawn;
D5 X-Accel-Buffering: no on both SSE header sites; D6 single log line
per affected request.

Scope-locked: does not touch CLAUDE_TIMEOUT semantics, the separate
server.mjs:480-489 dangling-client bug, issues #41/#42, or the
non-streaming path.

Includes privacy preflight and cloud-testing plan per maintainer
feedback.

Refs: #47

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(plan): implementation plan for #47 SSE heartbeat

6 phases: pre-work (file 480-bug), implementation (5 tasks on
feat/47-sse-heartbeat), opus fresh-context review, cloud verification
on Mac rig, privacy preflight, PR+release.

Each implementation task carries concrete code, syntax check, and a
scoped commit message. LOC budget enforced in Task 1.6 gate (~45
server.mjs lines max). Reviewer checklist scopes scope-lock, ALIGNMENT,
privacy, and heartbeat-cannot-abort discipline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(server): add startHeartbeat helper + HEARTBEAT_INTERVAL env var

Per design doc (refs #47). Helper is a per-request idle watchdog that
emits `: keepalive\n\n` SSE comment frames; returns a {reset, stop} handle.
No wiring yet — helper is unused, safe to commit in isolation.

cli.js citation: N/A — SSE response shaping is an OCP-owned translation
layer, not a cli.js operation. See AGENTS.md and ALIGNMENT.md Rule 2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(server): eagerly send SSE headers post-spawn (D4, refs #47)

Moves the ensureHeaders() call from "on first stdout byte" to
"immediately after successful spawn." This is a prerequisite for the
heartbeat covering the pre-first-byte silent window (the 'processing
large contexts' failure mode in #47).

Behavioral consequence: the narrow "spawn succeeded but subprocess died
before any byte" branch at server.mjs:610-611 becomes effectively dead
in the common case. The post-headers SSE-stop path (612-619) handles
it instead. The branch remains defensively for the client-closed-before-
ensureHeaders race.

Isolated commit per design doc §D4 so reviewer can focus on this one
behavior change.

cli.js citation: N/A — SSE header emission is OCP response-shaping.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(server): wire heartbeat into streaming path (refs #47)

- sendSSE() accepts optional hb handle and calls hb.reset() before write
- callClaudeStreaming starts heartbeat after ensureHeaders() and passes
  hb to the three streaming sendSSE call sites
- All three exit paths (proc close, proc error, res close) call
  hb.stop() to guarantee timer cleanup; no-op handle when disabled
  means zero runtime cost when CLAUDE_HEARTBEAT_INTERVAL=0

Heartbeat never aborts — only writes comment frames and re-arms. Aligns
with v3.3 timeout discipline (single CLAUDE_TIMEOUT, no secondary
client-killing timers).

cli.js citation: N/A — SSE response shaping is OCP translation layer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(server): add X-Accel-Buffering: no to SSE response headers (refs #47)

nginx (and many LBs / Cloudflare) default to proxy_buffering=on, which
would buffer heartbeat comment frames indefinitely and defeat the
feature silently. This header hints no-buffering; other stacks ignore
it. Applied at both SSE header sites (real streaming + cache-hit).

cli.js citation: N/A — response header shaping is OCP translation layer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(release): v3.12.0 — streaming heartbeat (refs #47)

Bundles the release-kit companion files per Iron Rule 5.2 / 11 example:
version bump across package.json + ocp-plugin + openclaw.plugin.json,
CHANGELOG v3.12.0 section, README env var row + "Streaming heartbeat"
explainer.

Tag push to v3.12.0 triggers .github/workflows/release.yml to create
the GitHub Release automatically.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(server): ensureHeaders returns true when already sent (refs #47)

Phase 3 smoke test revealed every content chunk was being dropped
after the D4 eager ensureHeaders() call: the stdout.on('data') guard
`if (!ensureHeaders()) return;` early-returned on every chunk because
ensureHeaders returned false for the already-sent case (conflated with
the dead-connection case).

Split the two conditions explicitly: return false only when res is
ended/destroyed; return true when headers are (already or now) sent.
This also fixes a latent multi-chunk bug on main that was masked
because claude CLI typically outputs in one stdout chunk.

Verified: node -c server.mjs; subsequent re-run of Phase 3 smoke test
now sees streaming content chunks + heartbeat frames.

cli.js citation: N/A — SSE response shaping is OCP translation layer.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v3.12.0 (2026-04-25)
+
+### Features
+
+- **Streaming heartbeat** — opt-in SSE comment frame (`: keepalive\n\n`) emitted during silent windows on the streaming response. Controlled by `CLAUDE_HEARTBEAT_INTERVAL` env var (ms; `0` = disabled, default). Covers both pre-first-byte and mid-stream tool-use pauses. Addresses #47. See [design doc](docs/superpowers/specs/2026-04-25-47-sse-heartbeat-design.md).
+- **`X-Accel-Buffering: no`** response header added to SSE responses so heartbeats survive nginx/Cloudflare default buffering.
+
+### Behavior changes
+
+- SSE headers are now sent immediately after the claude CLI spawns successfully, not on first stdout byte. The rare "spawn succeeded but subprocess died before any byte" path now closes the SSE stream cleanly rather than returning a JSON error.
+
+### Config additions
+
+| Variable | Default | Description |
+|---|---|---|
+| `CLAUDE_HEARTBEAT_INTERVAL` | `0` (disabled) | Interval in ms for SSE keepalive comment frames on streaming path. Resets on every real frame. |
+
 ## v3.11.1 — 2026-04-21
 
 ### Fixes

README.md

@@ -593,6 +593,7 @@ Future `ocp update` invocations sync automatically.
 | `OCP_ADMIN_KEY` | *(unset)* | Admin key for key management (multi mode) |
 | `CLAUDE_BIN` | *(auto-detect)* | Path to claude binary |
 | `CLAUDE_TIMEOUT` | `600000` | Request timeout (ms, default: 10 min) |
+| `CLAUDE_HEARTBEAT_INTERVAL` | `0` | Streaming SSE keepalive interval (ms). `0` = disabled. See "Streaming heartbeat" section. |
 | `CLAUDE_MAX_CONCURRENT` | `8` | Max concurrent claude processes |
 | `CLAUDE_MAX_PROMPT_CHARS` | `150000` | Prompt truncation limit (chars) |
 | `CLAUDE_SESSION_TTL` | `3600000` | Session expiry (ms, default: 1 hour) |
@@ -603,6 +604,16 @@ Future `ocp update` invocations sync automatically.
 | `PROXY_API_KEY` | *(unset)* | Bearer token for shared-mode authentication |
 | `PROXY_ANONYMOUS_KEY` | *(unset)* | Well-known anonymous key allowlist (multi mode). When set, this exact string bypasses `validateKey()` and grants public access. Exposed via `/health.anonymousKey` so clients auto-discover. See [Anonymous Access](#anonymous-access-optional). |
 
+### Streaming heartbeat
+
+When `CLAUDE_HEARTBEAT_INTERVAL` is set to a positive integer (milliseconds), OCP emits an SSE comment frame (`: keepalive\n\n`) on streaming responses whenever the stream has been idle for that duration. The timer resets on every real chunk, so heartbeats only fire during genuine silent windows (for example, Claude CLI tool-use pauses of 30s–5min, or a long "processing large contexts" delay before the first token).
+
+Use cases: downstream HTTP clients or load balancers with idle-connection timeouts that would otherwise abort a slow-but-alive request. `CLAUDE_HEARTBEAT_INTERVAL=30000` (30s) is a reasonable starting value if your downstream has a 60s idle timeout.
+
+Heartbeats are inert SSE comment lines — conforming SSE clients ignore them. If your downstream client's SSE parser crashes on comment frames, leave this disabled (the default) and file an issue so we can consider an alternate frame format.
+
+OCP also sends `X-Accel-Buffering: no` on SSE responses so nginx-default proxy buffering does not hold heartbeats in an upstream buffer.
+
 ## Security
 
 - **Localhost by default** — binds to `127.0.0.1`; set `CLAUDE_BIND=0.0.0.0` to enable LAN access

docs/superpowers/specs/2026-04-25-47-sse-heartbeat-design.md

@@ -0,0 +1,193 @@
+# Design: SSE Heartbeat on Streaming Path
+
+**Issue:** [#47](https://github.com/dtzp555-max/ocp/issues/47)
+**Date:** 2026-04-25
+**Status:** Draft (awaiting maintainer approval)
+**Target version:** v3.12.0 (minor — new opt-in feature + env var)
+
+---
+
+## Overview
+
+Add an opt-in idle-watchdog heartbeat to OCP's streaming response. When enabled, OCP emits an SSE comment frame (`: keepalive\n\n`) whenever the stream has been idle for a configurable interval. Timer resets on every real frame. Covers both pre-first-byte and mid-stream silent windows. Default **disabled**. Zero behavior change for existing deployments on upgrade.
+
+Companion tweak: `X-Accel-Buffering: no` response header added to both SSE header sites so heartbeats survive nginx-default proxy buffering.
+
+## Motivation
+
+Per [#47](https://github.com/dtzp555-max/ocp/issues/47): when `claude -p` takes a long time to respond (processing large contexts, or executing long tool calls that pause the token stream for 30s–5min), OCP emits no bytes to the downstream client for up to 600s. The caller cannot distinguish "slow but alive" from "hung." A recent incident reported 15 consecutive 600s silent waits cascading into a 2-hour downstream gateway outage.
+
+SSE heartbeats at the application layer let a caller observe liveness without OCP introducing any new client-killing timer.
+
+## Key decisions (with rationale)
+
+Six decisions were fixed during brainstorming. Each is presented as "decision → rationale" so future readers can judge whether a decision is still load-bearing.
+
+### D1. Coverage: whole-stream with idle-watchdog reset-on-byte
+
+A per-request timer starts when SSE headers are written and resets on every real `sendSSE()` call. Heartbeat fires only during genuine idle windows — never during healthy token bursts.
+
+**Rationale.** The `server.mjs:8-10` comment documents Claude tool-use pauses as "30s-5min pauses in the token stream." This means silent windows happen both pre-first-byte AND mid-stream. Covering only one of the two windows means re-opening this issue in three months when a different user reports the uncovered case. The reset-on-byte discipline is a ~2-LOC discipline (`clearTimeout` + `setTimeout` inside `sendSSE`) and is the standard "idle watchdog" pattern.
+
+### D2. Frame format: SSE comment (`: keepalive\n\n`)
+
+**Rationale.** Per SSE spec / MDN, lines starting with `:` are comments and MUST be ignored by conforming parsers. This is the maximally inert shape we can emit. Alternatives considered:
+- `event: ping` named event — Anthropic's own Messages API uses this, but on an OpenAI-compatible surface, downstream clients don't recognize that event name, so risk of client confusion is higher.
+- Empty-delta JSON chunk — parser-safe on OpenAI-compatible clients but burns an event id and is less observably "a heartbeat" in logs.
+
+The known risk with SSE comments is that some SDKs crash on empty comment frames (`openai-go` issue #556). The default-disabled posture (D3) mitigates this: users who opt in can also verify their client tolerates comments. If the comment format turns out to be broken in the wild for common OCP callers, we can add a second format behind `CLAUDE_HEARTBEAT_FORMAT` in a follow-up — **not in this PR**.
+
+### D3. Default disabled
+
+`CLAUDE_HEARTBEAT_INTERVAL=0` (meaning disabled) is the default when the env var is unset. Any positive integer enables at that ms interval.
+
+**Rationale.** Existing deployments see zero byte-shape change on upgrade. Users who have pingvvino's problem set the env var and get the fix. This is a reversible posture: once field evidence shows comment frames are safe across current OCP callers, a future minor can flip the default to `30000`.
+
+### D4. Header relocation: `ensureHeaders()` moves earlier
+
+Currently `ensureHeaders()` is invoked inside the `proc.stdout` handler, so SSE headers are written only on first byte from claude CLI. This PR moves the `ensureHeaders()` call to immediately after successful `spawn()` return.
+
+**Rationale.** You cannot emit SSE frames before sending SSE headers. For heartbeats to cover the pre-first-byte silent window (pingvvino's "processing large contexts" case), headers must be sent earlier. Behavioral consequence: the narrow "spawn succeeded but subprocess erroneously died before any byte" branch — currently a JSON error response — becomes an SSE error event + `[DONE]` + `res.end()`. Pre-spawn errors (before `spawn()`) still return JSON, unchanged. The affected path is rare (claude CLI either spawns or it doesn't).
+
+### D5. Transport-layer buffering hint: `X-Accel-Buffering: no`
+
+Added to both SSE response header sites (real-streaming `ensureHeaders()` and the cache-hit simulated-streaming header write).
+
+**Rationale.** nginx (and many LBs / Cloudflare) default to buffering proxied responses. Without this header, heartbeat bytes may accumulate in an upstream buffer and never reach the client, defeating the feature silently. This header is a nginx-specific hint; other stacks ignore it. 1 line per site, 2 sites total, indistinguishable-from-no-op for stacks that don't use it.
+
+### D6. Observability: single log line per affected request
+
+On the first heartbeat fire within a request, emit a structured log entry (`logEvent("info", "heartbeat_active", { session, intervalMs })`). No log spam for subsequent fires in the same request.
+
+**Rationale.** For a first-mover feature the question "did the heartbeat actually work for that hung request?" needs to be answerable from the existing `/logs` endpoint alone, without external tooling. One line per affected request gives proof-of-life without polluting the log stream during healthy traffic (where the timer resets and never fires).
+
+## Architecture
+
+Single-file change in `server.mjs`. One new helper plus small patches to existing sites.
+
+```
+startHeartbeat(res, intervalMs, sessionId) → { reset(), stop() }
+  if intervalMs <= 0: return no-op handle
+  internal: handle = setTimeout(intervalMs, onFire)
+  onFire():
+    res.write(": keepalive\n\n")
+    if !hasFired: logEvent("info", "heartbeat_active", { session, intervalMs }); hasFired = true
+    handle = setTimeout(intervalMs, onFire)
+  reset(): clearTimeout(handle); handle = setTimeout(intervalMs, onFire)
+  stop():  clearTimeout(handle); handle = null
+```
+
+Handle created once per streaming request. `sendSSE()` calls `heartbeat.reset()` before its `res.write()`. All exit paths call `heartbeat.stop()`.
+
+## Components and LOC budget
+
+| Location | Change | Est LOC |
+|---|---|---|
+| `server.mjs` env block | Parse `CLAUDE_HEARTBEAT_INTERVAL` | 1 |
+| `server.mjs` new `startHeartbeat()` function | Per spec above | 12 |
+| `server.mjs:565-579` `ensureHeaders()` | Add `"X-Accel-Buffering": "no"` to header object | 1 |
+| `server.mjs:~548-554` streaming entry | Move `ensureHeaders()` call to post-spawn; create heartbeat handle | 3 (net) |
+| `server.mjs:669` `sendSSE()` | Accept optional `hb` param; call `hb?.reset()` before `res.write()` | 2 |
+| `server.mjs` streaming exit hooks (proc 'close', proc 'error', req 'close') | Call `hb.stop()` | 3 |
+| `server.mjs:~610-611` pre-first-byte error branch | If headers sent, SSE error + `[DONE]` + `res.end()` instead of JSON | 3 |
+| `server.mjs:1171` cache-hit header write | Add `"X-Accel-Buffering": "no"` | 1 |
+| `README.md` env var table | One new row | 1 |
+| `README.md` new short section | "Streaming heartbeat" paragraph + nginx note | 5 |
+| `CHANGELOG.md` new v3.12.0 entry | Features + Config additions | 4 |
+| `package.json` + `ocp-plugin/package.json` + `ocp-plugin/openclaw.plugin.json` | Version bump 3.11.1 → 3.12.0 | 3 |
+
+**Estimated total: ~40 lines.** This is 5–10 lines over the 25–35 budget set in brainstorming. The overshoot is accounted for by D4 (header relocation + SSE error branch) and D5 (X-Accel-Buffering at two sites). Reviewer may reject if actual code lands materially larger than ~45 lines of server.mjs code excluding docs and version files.
+
+## Data flow (streaming request, heartbeat enabled)
+
+1. Client sends `POST /v1/chat/completions` with `stream=true`.
+2. Cache miss → `callClaudeStreaming()` invoked.
+3. `spawn()` claude subprocess succeeds → `ensureHeaders(res)` writes SSE headers including `X-Accel-Buffering: no`.
+4. `const hb = startHeartbeat(res, HEARTBEAT_INTERVAL, sessionId)` arms the watchdog (no-op if interval is 0).
+5. Watchdog ticks after `HEARTBEAT_INTERVAL` ms of idle. On fire: `: keepalive\n\n` out; first-fire logs once; re-arm.
+6. Every real `sendSSE()` write calls `hb.reset()` — cancels and re-arms timer.
+7. Healthy token bursts → heartbeat never fires.
+8. Tool-use pause → timer elapses → heartbeat fires → client stays alive → re-arm → repeat until next chunk arrives.
+9. On proc 'close' (success / `[DONE]`) / proc 'error' / req 'close' / `CLAUDE_TIMEOUT` kill → `hb.stop()`.
+
+## Error handling
+
+- **Client disconnect mid-heartbeat.** `req.on('close')` fires → `hb.stop()`. Any in-flight write becomes a no-op / emits `'error'` on `res`; existing code already tolerates this.
+- **`CLAUDE_TIMEOUT` (600s) fires mid-request.** Existing timeout handler SIGTERM's subprocess → proc 'close' → `hb.stop()`. This PR does **not** fix the separate issue that the current timeout path does not `res.end()` or emit an SSE error frame; that is documented as a separate issue.
+- **`spawn()` throws synchronously.** Heartbeat never started. Existing JSON error response unchanged.
+- **`spawn()` succeeds, subprocess errors before first byte.** Headers have already been written (per D4). Branch emits an SSE error event + `[DONE]` + `res.end()` instead of a JSON error. Documented behavior change.
+
+## Testing plan
+
+OCP has no unit test framework beyond `test-features.mjs`. Verification is manual + cloud-backed.
+
+### Manual local smoke test
+
+1. Set `CLAUDE_HEARTBEAT_INTERVAL=5000` (5s for easy observation) and start OCP.
+2. Issue a streaming completion with a prompt that triggers a tool-use pause (e.g., ask for a large file read or long reasoning):
+   ```
+   curl -N http://localhost:3456/v1/chat/completions \
+     -H "Authorization: Bearer $OCP_KEY" \
+     -d '{"model":"claude-opus-4-7","stream":true,
+           "messages":[{"role":"user","content":"read the attached 200KB text and summarize"}]}'
+   ```
+3. Confirm `: keepalive` comment lines appear in the raw response during the pause, at ~5s cadence.
+4. Confirm `/logs` shows exactly one `heartbeat_active` entry for the request.
+5. With `CLAUDE_HEARTBEAT_INTERVAL=0` (default), confirm no heartbeats and no log line.
+
+### Cloud-backed test run (pre-push, required)
+
+Per project feedback, tests must pass before any push to the public repo. Options, in preference order:
+
+1. **GitHub Actions** — add a temporary smoke workflow (or piggyback on an existing one) that runs `test-features.mjs` against a sandboxed claude mock. Not viable if `test-features.mjs` requires a real claude CLI auth.
+2. **Remote Linux test host via cc-chat handoff** — push feature branch, instruct a cloud machine with claude CLI installed to run the manual steps above, capture output, return verdict via cc-chat.
+3. **Docker/compose locally** — if the maintainer has Docker available, `docker-compose.yml` is present and can be extended.
+
+The implementation subagent and the reviewer subagent MUST include the chosen verification evidence in the PR body (command + output excerpt, sanitized of any identifiers) before the PR is opened for merge review.
+
+### Downstream-parser compatibility
+
+Before merging, verify at least one real downstream client (OCP's own `ocp-connect`, plus — if feasible — the current OpenClaw gateway) does not crash on comment frames. If a target client crashes, either (a) adjust the default to 0 and document the incompatibility, or (b) scope a follow-up PR for `CLAUDE_HEARTBEAT_FORMAT=empty-delta` as an alternative.
+
+## Privacy preflight (for public-repo push)
+
+Before `gh pr create` or any `git push` to `dtzp555-max/ocp`, run the following scan on the full diff (`git diff origin/main...HEAD`):
+
+1. **Use OCP's PR template privacy self-check** — the `.github/PULL_REQUEST_TEMPLATE.md` Privacy self-check section is the canonical list. Fill every checkbox.
+2. **Run `.gitleaks.toml` via gitleaks if available.**
+3. **Manual grep on the diff** for these patterns (sanitize any hits before commit):
+   - Personal names in any language (check commit-author trailers especially — `Co-Authored-By` lines have leaked names before).
+   - Email addresses beyond automated placeholders (`noreply@*`).
+   - Local paths like `/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>\` — replace with `$HOME/` or `~/`.
+   - Machine hostnames — use role-based names or generic descriptors.
+   - IPs, internal URLs, tailnet names.
+4. **Log samples and test output** pasted into spec / README / CHANGELOG / PR body must be sanitized pre-paste, not pre-push. This spec doc itself was drafted under this discipline.
+
+Historical reference: PR #43 / postmortem #44 (2026-04-22) scrubbed a prior leak and established the current apparatus. The user has explicitly flagged this as a scar to avoid re-treading for this PR.
+
+## Scope lock (out of scope)
+
+- `server.mjs:480-489` `CLAUDE_TIMEOUT` dangling-client behavior (no `res.end()` / no SSE error frame on timeout kill) — **will be filed as a separate issue** before this PR opens.
+- Issue #41 (handleSessionFailure deletes on resume only) — separate.
+- Issue #42 (SESSION_TTL and `lastUsed` interaction) — separate.
+- Any new first-byte / idle / adaptive-tier timeout logic — explicitly forbidden per the v3.3 lesson (`server.mjs:8-11`, commit 3843ec8).
+- Non-streaming chat path — no HTTP-level fix possible per [#47](https://github.com/dtzp555-max/ocp/issues/47)'s own conclusion.
+- Named-event format (`event: ping`) or empty-delta JSON chunk variants — possible follow-up PR if field evidence shows comment frames break real clients.
+- Changes to `CLAUDE_TIMEOUT` default — unchanged (stays 600s).
+- Circuit breaker revival — explicitly forbidden.
+
+## ALIGNMENT.md disposition
+
+`cli.js` does not itself emit SSE heartbeat frames — claude CLI speaks newline-delimited JSON to stdout, not SSE. SSE is an OCP-owned translation layer. Per `ALIGNMENT.md` Rule 2 / `AGENTS.md` ("OCP forwards, observes, and multiplexes traffic that cli.js already emits"): heartbeats are a translation-layer response-shaping concern, not a new endpoint and not a behavior mimicry. The PR body will state this explicitly in the `cli.js` citation checkbox and reference this design doc.
+
+## IDR (Iron Rule 11) disposition
+
+Single PR. Scope is one feature (SSE heartbeat) × one layer (streaming response formatting) × one severity (minor opt-in addition). Release-kit companion files (version bump, CHANGELOG, README) are bundled with the code change per the explicit Iron Rule 11 example ("版本 bump 相关的小改动 + README + CHANGELOG 可以同 PR"). The separate filings for the dangling-client bug (`server.mjs:480-489`) and any follow-up heartbeat format variants are IDR-compliant — each lands as its own PR.
+
+## Related
+
+- Issue: [#47](https://github.com/dtzp555-max/ocp/issues/47)
+- Prior timeout scar: commit 3843ec8 (v3.3.0 "simplify timeout to single CLAUDE_TIMEOUT")
+- Prior privacy scar: PR [#43](https://github.com/dtzp555-max/ocp/pull/43) / postmortem [#44](https://github.com/dtzp555-max/ocp/issues/44)
+- Constitution: `ALIGNMENT.md`
+- Project instructions: `AGENTS.md`, `CLAUDE.md`

ocp-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "ocp",
   "name": "OCP Commands",
   "description": "Slash commands for the OpenClaw Proxy — /ocp usage, /ocp settings, /ocp health, etc.",
-  "version": "3.3.1",
+  "version": "3.12.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

ocp-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocp",
-  "version": "3.3.1",
+  "version": "3.12.0",
   "description": "Slash commands for the OpenClaw Proxy",
   "main": "index.js",
   "type": "module",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-claude-proxy",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.",
   "type": "module",
   "bin": {

server.mjs

@@ -25,6 +25,7 @@
  *   CLAUDE_BREAKER_WINDOW        — sliding window duration in ms (default: 300000 = 5min)
  *   CLAUDE_BREAKER_HALF_OPEN_MAX — max concurrent probes in half-open state (default: 2)
  *   PROXY_API_KEY                — Bearer token for API auth (optional)
+ *   CLAUDE_HEARTBEAT_INTERVAL    — SSE heartbeat interval in ms on streaming path (default: 0 = disabled)
  */
 import { createServer } from "node:http";
 import { spawn, execFileSync } from "node:child_process";
@@ -94,6 +95,7 @@ const BREAKER_THRESHOLD = parseInt(process.env.CLAUDE_BREAKER_THRESHOLD || "6",
 const BREAKER_COOLDOWN = parseInt(process.env.CLAUDE_BREAKER_COOLDOWN || "120000", 10);
 const BREAKER_WINDOW = parseInt(process.env.CLAUDE_BREAKER_WINDOW || "300000", 10);
 const BREAKER_HALF_OPEN_MAX = parseInt(process.env.CLAUDE_BREAKER_HALF_OPEN_MAX || "2", 10);
+const HEARTBEAT_INTERVAL = parseInt(process.env.CLAUDE_HEARTBEAT_INTERVAL || "0", 10);
 const BIND_ADDRESS = process.env.CLAUDE_BIND || "127.0.0.1";
 const NO_CONTEXT = process.env.CLAUDE_NO_CONTEXT === "true";
 const AUTH_MODE = process.env.CLAUDE_AUTH_MODE || (PROXY_API_KEY ? "shared" : "none");
@@ -542,6 +544,33 @@ function callClaude(model, messages, conversationId) {
   });
 }
 
+// ── SSE heartbeat (opt-in idle watchdog) ────────────────────────────────
+// Emits `: keepalive\n\n` SSE comment frames during silent windows on the
+// streaming response. Design: docs/superpowers/specs/2026-04-25-47-sse-heartbeat-design.md
+// This is a downstream liveness hint only — it MUST NOT be able to abort
+// or time out a request. That discipline is load-bearing: v2.2-v2.5's
+// first-byte/adaptive-tier timeouts "repeatedly killed valid requests"
+// (see server.mjs top-of-file comment and commit 3843ec8).
+function startHeartbeat(res, intervalMs, sessionId) {
+  if (!intervalMs || intervalMs <= 0) return { reset: () => {}, stop: () => {} };
+  let handle = null;
+  let hasFired = false;
+  const onFire = () => {
+    if (res.writableEnded || res.destroyed) return;
+    res.write(": keepalive\n\n");
+    if (!hasFired) {
+      hasFired = true;
+      logEvent("info", "heartbeat_active", { session: sessionId, intervalMs });
+    }
+    handle = setTimeout(onFire, intervalMs);
+  };
+  handle = setTimeout(onFire, intervalMs);
+  return {
+    reset: () => { if (handle) { clearTimeout(handle); handle = setTimeout(onFire, intervalMs); } },
+    stop:  () => { if (handle) { clearTimeout(handle); handle = null; } },
+  };
+}
+
 // ── Call claude CLI (real streaming) ─────────────────────────────────────
 // Pipes stdout from the claude process directly to SSE chunks as they arrive.
 // Each data chunk becomes a proper SSE event with delta content in real time.
@@ -563,12 +592,14 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
   let cachedContent = ""; // accumulate for cache write-back
 
   function ensureHeaders() {
-    if (headersSent || res.writableEnded || res.destroyed) return false;
+    if (res.writableEnded || res.destroyed) return false;
+    if (headersSent) return true;
     headersSent = true;
     res.writeHead(200, {
       "Content-Type": "text/event-stream",
       "Cache-Control": "no-cache",
       "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
     });
     // Send initial role chunk
     sendSSE(res, {
@@ -578,6 +609,15 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
     return true;
   }
 
+  // D4 (spec 2026-04-25): eagerly send SSE headers post-spawn so the
+  // heartbeat started in the next statement (Task 1.3) covers the
+  // pre-first-byte silent window. Behavior change: the `code !== 0`
+  // before-first-byte branch at server.mjs:610-611 becomes effectively
+  // unreachable in the common case — the post-headers SSE-stop path
+  // (612-619) handles it instead.
+  ensureHeaders();
+  const hb = startHeartbeat(res, HEARTBEAT_INTERVAL, convId);
+
   proc.stdout.on("data", (d) => {
     markFirstByte();
     const text = d.toString();
@@ -590,13 +630,14 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
     sendSSE(res, {
       id, object: "chat.completion.chunk", created, model,
       choices: [{ index: 0, delta: { content: text }, finish_reason: null }],
-    });
+    }, hb);
   });
 
   proc.stderr.on("data", (d) => (stderr += d));
 
   proc.on("close", (code, signal) => {
     activeProcesses.delete(proc);
+    hb.stop();
     cleanup();
     const elapsed = Date.now() - t0;
 
@@ -613,7 +654,7 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
         sendSSE(res, {
           id, object: "chat.completion.chunk", created, model,
           choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
-        });
+        }, hb);
         res.write("data: [DONE]\n\n");
         res.end();
       }
@@ -632,7 +673,7 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
         sendSSE(res, {
           id, object: "chat.completion.chunk", created, model,
           choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
-        });
+        }, hb);
         res.write("data: [DONE]\n\n");
         res.end();
       }
@@ -641,6 +682,7 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
 
   proc.on("error", (err) => {
     console.error(`[claude] spawn error: ${err.message}`);
+    hb.stop();
     cleanup();
     trackError(err.message);
     handleSessionFailure();
@@ -653,6 +695,7 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
 
   // If client disconnects, kill the process to free resources
   res.on("close", () => {
+    hb.stop();
     if (!proc.killed) {
       try { proc.kill("SIGTERM"); } catch {}
     }
@@ -666,7 +709,8 @@ function jsonResponse(res, status, data) {
   res.end(JSON.stringify(data));
 }
 
-function sendSSE(res, data) {
+function sendSSE(res, data, hb) {
+  hb?.reset();
   res.write(`data: ${JSON.stringify(data)}\n\n`);
 }
 
@@ -1168,7 +1212,7 @@ async function handleChatCompletions(req, res) {
           // Simulate streaming for cached response
           const id = `chatcmpl-${randomUUID()}`;
           const created = Math.floor(Date.now() / 1000);
-          res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "Connection": "keep-alive" });
+          res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no" });
           sendSSE(res, { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }] });
           sendSSE(res, { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: { content: cached.response }, finish_reason: null }] });
           sendSSE(res, { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: {}, finish_reason: "stop" }] });