@chorus-aidlc/chorus 0.14.1 → 0.14.3

package/README.zh.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/images/chorus-slug.png" alt="Chorus" width="240" />
+  <img src="packages/landing/public/images/chorus-slug.png" alt="Chorus" width="240" />
 </p>
 
 <p align="center"><strong>面向 AI 与人类协作的 Agent Harness</strong></p>
@@ -171,7 +171,7 @@ daemon 启动时的横幅会打印它**实际读取的 `daemon.json` 路径**（
 
 ### 远程唤醒 Agent——派活到指定目录，实时看它跑
 
-![远程唤醒 Agent](docs/images/agent-daemon-wake.gif)
+![远程唤醒 Agent](packages/landing/public/images/agent-daemon-wake.gif)
 
 把一条想法派给远程 Agent 的某个目录，打开对话窗口，就能实时看到本地的 Claude Code 接活、开跑，全程不用碰终端，也不用手动 resume。
 
@@ -183,7 +183,7 @@ Chorus 自动把整个项目整理成一张思维导图——想法、提案、
 
 ### Proposal——AI Agent 实时生成计划
 
-![Proposal Presence](docs/images/proposal-presence.gif)
+![Proposal Presence](packages/landing/public/images/proposal-presence.gif)
 
 PM Agent 分析需求并实时生成包含 PRD 和任务 DAG 的提案，Presence 指示器实时显示 Agent 活动状态。
 
@@ -195,37 +195,37 @@ PM Agent 分析需求并实时生成包含 PRD 和任务 DAG 的提案，Presenc
 
 ### Kanban——任务状态实时流转
 
-![Kanban Presence](docs/images/kanban-presence.gif)
+![Kanban Presence](packages/landing/public/images/kanban-presence.gif)
 
 Kanban 看板随 Agent 工作进度自动更新，任务卡片在 To Do → In Progress → To Verify 之间实时流转。Presence 指示器高亮显示正在被操作的资源。
 
 ### 看板 & 任务 DAG
 
-![Kanban & Task DAG](docs/images/kanan-dag.png)
+![Kanban & Task DAG](packages/landing/public/images/kanban-dag.png)
 
 看板追踪任务状态，DAG 展示依赖关系和并行路径，一目了然。
 
 ### Idea & 需求细化
 
-![Idea & Elaboration](docs/images/idea-elaborate.png)
+![Idea & Elaboration](packages/landing/public/images/idea-elaborate.png)
 
 PM Agent 在创建 Proposal 前，通过结构化问答轮次澄清需求。面板展示 Idea 详情及已完成的细化轮次。
 
 ### 提案审阅
 
-![Proposal Review](docs/images/proposal.png)
+![Proposal Review](packages/landing/public/images/proposal.png)
 
 PM Agent 生成的 Proposal 包含文档草稿和任务 DAG 草稿，Admin 在此面板审阅并决定批准或驳回。
 
 ### 验收标准——双路验证
 
-![Acceptance Criteria](docs/images/task-ac.png)
+![Acceptance Criteria](packages/landing/public/images/task-ac.png)
 
 Dev Agent 自检 + Admin 独立审核，每条验收标准都有结构化的通过/失败证据。
 
 ### Universal Search——Cmd+K 全局搜索
 
-![Universal Search](docs/images/universal-search.png)
+![Universal Search](packages/landing/public/images/universal-search.png)
 
 Cmd+K 命令面板，支持跨 6 种实体类型搜索。支持范围筛选（全局/项目组/单项目）、按类型切换 Tab、键盘导航。Web UI 和 AI Agent（通过 `chorus_search` MCP 工具）共享同一搜索后端。
 
@@ -393,7 +393,7 @@ PGlite 在端口 5433 运行嵌入式 PostgreSQL。数据存储在 `.pglite/`，
 
 在 Web UI 的 **Settings → Agents → Create API Key** 创建 API Key。Key 以 `cho_` 开头，仅在创建时显示一次。
 
-![Create API Key](docs/images/create-key.png)
+![Create API Key](packages/landing/public/images/create-key.png)
 
 ---
 

package/cli/claude-spawner.mjs

@@ -247,6 +247,10 @@ export function parseNdjsonChunk(buffer, chunk, onObject, onWarn = () => {}) {
 export class ClaudeSpawner {
   /** @param {ClaudeSpawnerOptions} [opts] */
   constructor(opts = {}) {
+    this.sessionDecision = {
+      probeIsAuthoritative: true,
+      takeoverCommand: "claude --resume",
+    };
     this.claudePath = opts.claudePath ?? null;
     this.spawnImpl = opts.spawnImpl ?? spawn;
     this.logger = opts.logger ?? NOOP_LOGGER;

package/cli/codex-spawner.mjs

@@ -26,6 +26,11 @@ import { statSync } from "node:fs";
 import { win32 as pathWin32, posix as pathPosix } from "node:path";
 import { parseNdjsonChunk } from "./claude-spawner.mjs";
 import { getThreadId as defaultGetThreadId, setThreadId as defaultSetThreadId } from "./codex-session-map.mjs";
+import {
+  getCodexUsageSnapshot as defaultGetUsageSnapshot,
+  normalizeCodexUsageEvent,
+  setCodexUsageSnapshot as defaultSetUsageSnapshot,
+} from "./codex-usage-map.mjs";
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
@@ -88,9 +93,11 @@ export function buildCodexArgs({ isNew, threadId, permissionMode }) {
  */
 export function extractThreadId(obj) {
   if (!obj || typeof obj !== "object") return null;
-  if (obj.type === "thread.started" && typeof obj.thread_id === "string") return obj.thread_id;
+  if (obj.type === "thread.started" && typeof obj.thread_id === "string") {
+    return obj.thread_id.trim() || null;
+  }
   if (obj.type === "session_meta" && obj.payload && typeof obj.payload.id === "string") {
-    return obj.payload.id;
+    return obj.payload.id.trim() || null;
   }
   return null;
 }
@@ -163,11 +170,14 @@ export function resolveSpawnCommand(codexPath, args, platform = process.platform
  * @property {NodeJS.Platform} [platform]  Injectable for tests; gates POSIX `detached`.
  * @property {(anchor: string) => string|null} [getThreadIdFn]  Injectable session-map read.
  * @property {(anchor: string, threadId: string) => void} [setThreadIdFn]  Injectable session-map write.
+ * @property {(anchor: string, threadId: string) => object|null} [getUsageSnapshotFn]
+ * @property {(anchor: string, threadId: string, usage: object) => void} [setUsageSnapshotFn]
  */
 
 export class CodexSpawner {
   /** @param {CodexSpawnerOptions} [opts] */
   constructor(opts = {}) {
+    this.sessionDecision = { probeIsAuthoritative: false };
     this.codexPath = opts.codexPath ?? null;
     this.spawnImpl = opts.spawnImpl ?? spawn;
     this.logger = opts.logger ?? NOOP_LOGGER;
@@ -176,6 +186,8 @@ export class CodexSpawner {
     this.platform = opts.platform ?? process.platform;
     this.getThreadIdFn = opts.getThreadIdFn ?? defaultGetThreadId;
     this.setThreadIdFn = opts.setThreadIdFn ?? defaultSetThreadId;
+    this.getUsageSnapshotFn = opts.getUsageSnapshotFn ?? defaultGetUsageSnapshot;
+    this.setUsageSnapshotFn = opts.setUsageSnapshotFn ?? defaultSetUsageSnapshot;
     this.resolveCodexPathFn = opts.resolveCodexPathFn ?? resolveCodexPath;
   }
 
@@ -198,6 +210,13 @@ export class CodexSpawner {
     // waker's Claude transcript probe: a recorded thread id means resume.
     const knownThreadId = anchor ? this.getThreadIdFn(anchor) : null;
     const isNew = !knownThreadId;
+    let previousUsage = knownThreadId
+      ? this.getUsageSnapshotFn(anchor, knownThreadId)
+      : null;
+    // Existing threads created before this baseline store was introduced cannot
+    // yield a trustworthy first delta. Seed once and omit that turn's usage
+    // instead of publishing the entire historical cumulative total.
+    let needsUsageSeed = Boolean(knownThreadId && !previousUsage);
 
     const codexPath = this.codexPath ?? this.resolveCodexPathFn();
     if (!codexPath) {
@@ -249,6 +268,7 @@ export class CodexSpawner {
 
       let stdoutBuf = "";
       let observedThreadId = knownThreadId || null;
+      let threadIdPersisted = false;
 
       child.stdout?.setEncoding?.("utf8");
       child.stdout?.on("data", (chunk) => {
@@ -257,10 +277,27 @@ export class CodexSpawner {
           String(chunk),
           (obj) => {
             const tid = extractThreadId(obj);
-            if (tid) observedThreadId = tid;
+            if (tid) {
+              observedThreadId = tid;
+              if (isNew && anchor && !threadIdPersisted) {
+                threadIdPersisted = true;
+                this.setThreadIdFn(anchor, tid);
+              }
+            }
+            let delivered = obj;
+            if (obj?.type === "turn.completed" && obj.usage) {
+              delivered = needsUsageSeed
+                ? { ...obj, usage: null }
+                : normalizeCodexUsageEvent(obj, previousUsage);
+              if (anchor && observedThreadId) {
+                this.setUsageSnapshotFn(anchor, observedThreadId, obj.usage);
+              }
+              previousUsage = obj.usage;
+              needsUsageSeed = false;
+            }
             if (onMessage) {
               try {
-                onMessage(obj);
+                onMessage(delivered);
               } catch (err) {
                 this.logger.warn(`[Chorus] onMessage handler threw: ${err}`);
               }
@@ -285,12 +322,6 @@ export class CodexSpawner {
         if (code !== 0) {
           this.logger.warn(`[Chorus] codex exited with code ${code}`);
         }
-        // Persist anchor→thread_id only on a fresh, successful run that produced a
-        // new id — so a later wake for this anchor resumes it. Best-effort; the
-        // session map swallows its own IO errors.
-        if (code === 0 && isNew && anchor && observedThreadId) {
-          this.setThreadIdFn(anchor, observedThreadId);
-        }
         resolve({ sessionId: observedThreadId || anchor, exitCode: code, isNew });
       });
 

package/cli/codex-usage-map.mjs

@@ -0,0 +1,115 @@
+// Persist the last cumulative Codex token snapshot per Chorus anchor. Codex
+// `turn.completed.usage` is backed by ThreadTokenUsage.total, so resumed execs
+// must subtract this baseline before publishing per-turn usage.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const NOOP_LOGGER = { warn() {} };
+const FIELDS = [
+  "input_tokens",
+  "cached_input_tokens",
+  "cache_write_input_tokens",
+  "output_tokens",
+  "reasoning_output_tokens",
+];
+
+export function codexUsageMapPath() {
+  return join(homedir(), ".chorus", "codex-usage.json");
+}
+
+function tokenInt(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.trunc(value)
+    : null;
+}
+
+function sanitizeUsage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const usage = {};
+  let found = false;
+  for (const field of FIELDS) {
+    const parsed = tokenInt(value[field]);
+    if (parsed !== null) {
+      usage[field] = parsed;
+      found = true;
+    }
+  }
+  return found ? usage : null;
+}
+
+function readMap(path, read, logger) {
+  try {
+    const parsed = JSON.parse(read(path));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    if (!(err && err.code === "ENOENT")) {
+      logger.warn(`[Chorus] codex-usage-map: read failed (${err}) - treating as empty`);
+    }
+    return {};
+  }
+}
+
+export function getCodexUsageSnapshot(anchor, threadId, deps = {}) {
+  if (!anchor || !threadId) return null;
+  const path = deps.path ?? codexUsageMapPath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const logger = deps.logger ?? NOOP_LOGGER;
+  const entry = readMap(path, read, logger)[anchor];
+  if (!entry || entry.threadId !== threadId) return null;
+  return sanitizeUsage(entry.usage);
+}
+
+export function setCodexUsageSnapshot(anchor, threadId, usage, deps = {}) {
+  const clean = sanitizeUsage(usage);
+  if (!anchor || !threadId || !clean) return;
+  const path = deps.path ?? codexUsageMapPath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const rename = deps.rename ?? renameSync;
+  const logger = deps.logger ?? NOOP_LOGGER;
+  try {
+    const map = readMap(path, read, logger);
+    map[anchor] = { threadId, usage: clean };
+    mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    write(tmp, JSON.stringify(map, null, 2) + "\n", { mode: 0o600 });
+    rename(tmp, path);
+  } catch (err) {
+    logger.warn(`[Chorus] codex-usage-map: persist failed (${err}) - next turn may overcount`);
+  }
+}
+
+function delta(current, previous) {
+  const now = tokenInt(current);
+  if (now === null) return null;
+  const before = tokenInt(previous);
+  return before !== null && now >= before ? now - before : now;
+}
+
+export function normalizeCodexUsageEvent(event, previous) {
+  if (!event || event.type !== "turn.completed" || !event.usage) return event;
+  const raw = event.usage;
+  const input = delta(raw.input_tokens, previous?.input_tokens);
+  const cacheRead = delta(raw.cached_input_tokens, previous?.cached_input_tokens);
+  const cacheWrite = delta(raw.cache_write_input_tokens, previous?.cache_write_input_tokens);
+  const exclusiveInput =
+    input === null ? null : Math.max(0, input - (cacheRead ?? 0) - (cacheWrite ?? 0));
+
+  return {
+    ...event,
+    usage: {
+      ...raw,
+      input_tokens: exclusiveInput,
+      cached_input_tokens: cacheRead,
+      cache_write_input_tokens: cacheWrite,
+      output_tokens: delta(raw.output_tokens, previous?.output_tokens),
+      reasoning_output_tokens: delta(
+        raw.reasoning_output_tokens,
+        previous?.reasoning_output_tokens
+      ),
+    },
+  };
+}

package/cli/daemon-rest-client.mjs

@@ -16,6 +16,8 @@
 //                                                       startedAt|null }] }
 //   reportInterrupt  → POST /api/daemon/report-interrupt
 //                      { connectionUuid, entityType, entityUuid, reason }
+//   heartbeat        → POST /api/daemon/connection-heartbeat
+//                      { connectionUuid, connectedAt }
 //   readPendingTurns → GET  /api/daemon/pending-turns?connectionUuid=…
 //                      → { turns: [{ turnUuid, sessionId, directIdeaUuid, trigger,
 //                                    promptText }] }
@@ -72,6 +74,7 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *   transcript: (p: { sessionId: string, messages: Array<{ role: string, text: string }> }) => Promise<DaemonRestResult>,
  *   executionState: (p: { executions: Array<Record<string, unknown>> }) => Promise<DaemonRestResult>,
  *   reportInterrupt: (p: { entityType: string, entityUuid: string, reason: string }) => Promise<DaemonRestResult>,
+ *   heartbeat: (p: { connectionUuid: string, connectedAt: string }) => Promise<DaemonRestResult>,
  *   readPendingTurns: () => Promise<DaemonRestResult>,
  * }}
  */
@@ -136,16 +139,25 @@ export function createDaemonRestClient(opts) {
      * server resolves the turn by the session BUSINESS KEY (`sessionId`); the optional
      * `entityType`/`entityUuid` stamp the weak executionUuid link. An `interrupted`
      * status may carry `interruptedReason` (`user`/`crash`/`shutdown` — the server
-     * rejects `offline`, which is its own reconcile verdict). Requires the
-     * connectionUuid (the server addresses the turn against a connection the agent owns).
+     * rejects `offline`, which is its own reconcile verdict). A terminal edge may also
+     * carry `transcriptRelayError` — the daemon-known reason its transcript upload
+     * finally failed (fix #444 follow-up), persisted as a turn annotation — and `usage`,
+     * the whole normalized per-turn TokenUsage object (daemon-token-usage), persisted as
+     * the turn's usage. Both ride the terminal edge only. Requires the connectionUuid (the
+     * server addresses the turn against a connection the agent owns).
      */
-    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason }) {
+    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason, transcriptRelayError, usage }) {
       const connectionUuid = getConnectionUuid();
       if (!connectionUuid) {
         const error = `cannot advance turn for session ${sessionId} → ${status} — no connection uuid yet`;
         logger.warn(`[Chorus] ${error}`);
         return { ok: false, status: null, error, skipped: true };
       }
+      // Per-turn token usage (daemon-token-usage) is meaningful only on a TERMINAL edge —
+      // the daemon knows it at subprocess exit, exactly like transcriptRelayError. Guard on
+      // the terminal status here so a stray usage on → running is never sent (the server
+      // ignores it there anyway; this keeps the wire honest).
+      const isTerminal = status === "ended" || status === "interrupted";
       const body = {
         connectionUuid,
         sessionId,
@@ -154,6 +166,11 @@ export function createDaemonRestClient(opts) {
         ...(entityType && entityUuid ? { entityType, entityUuid } : {}),
         // Only meaningful alongside status=interrupted; never sent otherwise.
         ...(status === "interrupted" && interruptedReason ? { interruptedReason } : {}),
+        // Transcript-relay failure annotation (fix #444 follow-up): only sent when the
+        // daemon actually knows the upload failed (a truthy reason on a terminal edge).
+        ...(transcriptRelayError ? { transcriptRelayError } : {}),
+        // The whole normalized TokenUsage object, nested under `usage`, only on a terminal edge.
+        ...(usage && isTerminal ? { usage } : {}),
       };
       return post(
         "turn-advance",
@@ -223,6 +240,20 @@ export function createDaemonRestClient(opts) {
       );
     },
 
+    /**
+     * POST /api/daemon/connection-heartbeat — acknowledge receipt of one SSE heartbeat.
+     * The values come directly from the active stream's registration handshake; unlike
+     * other connection-scoped operations this must not resolve the uuid lazily, because
+     * a delayed acknowledgment must retain its original generation fence.
+     */
+    async heartbeat({ connectionUuid, connectedAt }) {
+      return post(
+        "connection-heartbeat",
+        "/api/daemon/connection-heartbeat",
+        { connectionUuid, connectedAt },
+      );
+    },
+
     /**
      * GET /api/daemon/pending-turns?connectionUuid=… — read this connection's unstarted
      * (pending) turns from the turn table (the reconnect-backfill / deliver_turn source).

package/cli/daemon.mjs

@@ -43,6 +43,7 @@ import {
 import { WAKE_ACTIONS } from "./prompts.mjs";
 import { createInterruptReporter } from "./interrupt-reporter.mjs";
 import { createTurnReporter } from "./turn-reporter.mjs";
+import { createDaemonRestClient } from "./daemon-rest-client.mjs";
 import { createControlHandler } from "./control-handler.mjs";
 import { resolveSigintTimeoutMs, resolveDaemonCwds } from "./daemon-config.mjs";
 import {
@@ -205,6 +206,13 @@ export function buildDaemon(creds, deps = {}) {
     // doesn't matter. Per-connection so each path's wakes report against the right row.
     /** @type {{ connectionUuid: string|null }} */
     const connectionState = { connectionUuid: null };
+    const daemonRestClient = createDaemonRestClient({
+      url: creds.url,
+      apiKey: creds.apiKey,
+      getConnectionUuid: () => connectionState.connectionUuid,
+      logger,
+      fetchImpl: deps.fetchImpl,
+    });
 
     // Per-connection terminal-outcome bookkeeping (add-daemon-connection-conflict-skip).
     // `resolved` guards recordConnectionOutcome against double-counting a reconnect's
@@ -389,6 +397,7 @@ export function buildDaemon(creds, deps = {}) {
           recordConnectionOutcome(outcome, false);
         },
         onControl,
+        acknowledgeHeartbeat: (registration) => daemonRestClient.heartbeat(registration),
         onReconnect: backfill,
         logger,
       });

package/cli/lineage.mjs

@@ -146,6 +146,26 @@ export class LineageResolver {
         `[Chorus] lineage: non-string directIdeaUuid for ${entityType}:${entityUuid}`
       );
     }
+    // A non-null ROOT idea with a null/absent DIRECT idea is a lineage gap: the wake will
+    // anchor the execution on the entity (task/proposal), never on the idea conversation,
+    // so its run shows no running indicator / Interrupt on the idea chat — permanently, for
+    // this class of wake. The overwhelmingly likely cause is a Chorus server that predates
+    // the `directIdeaUuid` field on the /root-idea endpoint. Surface it as a visible WARN
+    // rather than folding it into the generic success `info` below (where it is
+    // indistinguishable from the legitimate "no idea ancestor" outcome, root=direct=null).
+    // Diagnostic ONLY — we do NOT substitute the root for the missing direct idea: for a
+    // DERIVED child idea root ≠ direct, so falling back to root would light the PARENT
+    // conversation and leave the child (which owns the woken session) idle. The correct fix
+    // is server-side; this warn points the operator straight at it.
+    if (root !== null && direct === null) {
+      this.logger.warn(
+        `[Chorus] lineage: ${entityType}:${entityUuid} resolved a root idea (${root}) but NO ` +
+          `directIdeaUuid — this wake will anchor on the entity, not the idea conversation, ` +
+          `so its run will not show a running indicator / Interrupt on the idea chat. Most ` +
+          `likely the Chorus server predates the directIdeaUuid field on /root-idea; upgrade ` +
+          `the server to restore child-wake → idea-conversation matching.`
+      );
+    }
     this.logger.info(
       `[Chorus] lineage: ${entityType}:${entityUuid} → root ${root ?? "none"}, direct ${direct ?? "none"}` +
         (typeof data.resolvedVia === "string" ? ` (${data.resolvedVia})` : "")

package/cli/sse-listener.mjs

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 
 const INITIAL_DELAY_MS = 1_000;
 const MAX_DELAY_MS = 30_000;
+const WATCHDOG_TIMEOUT_MS = 75_000;
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
@@ -78,6 +79,8 @@ const PROCESS_STARTED_AT = new Date();
  *   The event carries `{ host, cwd }` of the conflicting identity.
  * @property {() => Promise<void>} [onReconnect]  Called after a reconnect so the
  *   caller can back-fill notifications missed during the gap.
+ * @property {(registration: {connectionUuid:string,connectedAt:string}) => Promise<unknown>} [acknowledgeHeartbeat]
+ *   Best-effort REST acknowledgment for a parsed heartbeat comment.
  * @property {string} [cwd]  The working directory THIS connection serves (T3 — 单
  *   daemon 多路径). A multi-path daemon runs one SseListener per declared path, each
  *   self-reporting its own cwd so the server registers them as distinct connections
@@ -88,6 +91,7 @@ const PROCESS_STARTED_AT = new Date();
  * @property {typeof fetch} [fetchImpl]  Injectable for tests.
  * @property {number} [initialDelayMs]
  * @property {number} [maxDelayMs]
+ * @property {number} [watchdogTimeoutMs] Injectable for deterministic tests only.
  */
 
 export class SseListener {
@@ -100,12 +104,14 @@ export class SseListener {
     this.onControl = opts.onControl ?? (() => {});
     this.onConflict = opts.onConflict ?? (() => {});
     this.onReconnect = opts.onReconnect ?? (async () => {});
+    this.acknowledgeHeartbeat = opts.acknowledgeHeartbeat ?? (async () => {});
     /** @type {string|null} The connection this stream registered as (once reported). */
     this.connectionUuid = null;
     this.logger = opts.logger ?? NOOP_LOGGER;
     this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     this.initialDelayMs = opts.initialDelayMs ?? INITIAL_DELAY_MS;
     this.maxDelayMs = opts.maxDelayMs ?? MAX_DELAY_MS;
+    this.watchdogTimeoutMs = opts.watchdogTimeoutMs ?? WATCHDOG_TIMEOUT_MS;
 
     // Build the self-reporting endpoint URL once and reuse it across every
     // (re)connect, so the reconnect path always re-sends the same params.
@@ -128,6 +134,7 @@ export class SseListener {
       host: hostname(),
       cwd: this.cwd,
       startedAt: PROCESS_STARTED_AT.toISOString(),
+      livenessAck: "v1",
     });
     this.endpoint = `${this.url}/api/events/notifications?${params.toString()}`;
 
@@ -136,14 +143,20 @@ export class SseListener {
     this.abortController = null;
     /** @type {ReturnType<typeof setTimeout> | null} */
     this.reconnectTimer = null;
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    this.watchdogTimer = null;
+    /** @type {{connectionUuid:string,connectedAt:string}|null} */
+    this.activeRegistration = null;
     this.reconnectDelay = this.initialDelayMs;
   }
 
   /** Open the SSE connection. On failure, schedules a backoff reconnect. */
   async connect() {
     this.#clearReconnectTimer();
+    this.#clearWatchdog();
     const abortController = new AbortController();
     this.abortController = abortController;
+    this.activeRegistration = null;
 
     let response;
     try {
@@ -173,6 +186,7 @@ export class SseListener {
     this.status = "connected";
     this.reconnectDelay = this.initialDelayMs;
     this.logger.info("[Chorus] SSE connection established");
+    this.#refreshWatchdog(abortController);
 
     if (wasReconnect) {
       try {
@@ -182,22 +196,25 @@ export class SseListener {
       }
     }
 
-    this.#consumeStream(response.body, abortController.signal);
+    this.#consumeStream(response.body, abortController);
   }
 
   /** Gracefully close the connection (no reconnect). */
   disconnect() {
     this.#clearReconnectTimer();
+    this.#clearWatchdog();
     if (this.abortController) {
       this.abortController.abort();
       this.abortController = null;
     }
     this.status = "disconnected";
+    this.activeRegistration = null;
     this.logger.info("[Chorus] SSE connection closed");
   }
 
-  /** @param {ReadableStream<Uint8Array>} body @param {AbortSignal} signal */
-  async #consumeStream(body, signal) {
+  /** @param {ReadableStream<Uint8Array>} body @param {AbortController} abortController */
+  async #consumeStream(body, abortController) {
+    const signal = abortController.signal;
     const decoder = new TextDecoder();
     const reader = body.getReader();
     let buffer = "";
@@ -205,6 +222,12 @@ export class SseListener {
       while (true) {
         const { done, value } = await reader.read();
         if (done || signal.aborted) break;
+        // Transport activity is byte arrival, not successful SSE parsing. Refresh before
+        // decode so comments, partial frames, and malformed payloads all prove the stream
+        // is still delivering bytes.
+        if (value && value.byteLength > 0) {
+          this.#refreshWatchdog(abortController);
+        }
         // Strip CR on ingest so CRLF transports (`\r\n\r\n` boundaries) parse the
         // same as LF — the `\n\n` boundary scan below would otherwise never match.
         buffer += decoder.decode(value, { stream: true }).replace(/\r/g, "");
@@ -219,6 +242,7 @@ export class SseListener {
       if (signal.aborted) return;
       this.logger.warn(`[Chorus] SSE stream error: ${err}`);
     } finally {
+      if (this.abortController === abortController) this.#clearWatchdog();
       try {
         reader.releaseLock();
       } catch {
@@ -235,7 +259,24 @@ export class SseListener {
   #processMessage(raw) {
     for (const line of raw.split("\n")) {
       // CR already stripped on ingest. Heartbeat / comment lines start with ":".
-      if (line.startsWith(":")) continue;
+      if (line.startsWith(":")) {
+        if (line.slice(1).trim() === "heartbeat" && this.activeRegistration) {
+          const registration = this.activeRegistration;
+          Promise.resolve()
+            .then(() => this.acknowledgeHeartbeat(registration))
+            .then((result) => {
+              if (result && typeof result === "object" && result.ok === false) {
+                // The REST client already logged the transport cause. Keep listener
+                // behavior best-effort and avoid adding a retry loop here.
+                return;
+              }
+            })
+            .catch((err) => {
+              this.logger.warn(`[Chorus] heartbeat acknowledgment failed: ${err}`);
+            });
+        }
+        continue;
+      }
       if (line.startsWith("data: ")) {
         const jsonStr = line.slice(6);
         let event;
@@ -248,8 +289,16 @@ export class SseListener {
         // The server's first data event tells us which DaemonConnection this
         // stream registered as. Capture it (for execution-state attribution) and
         // do NOT forward it as a notification — it isn't one.
-        if (event && event.type === "connection_registered" && typeof event.connectionUuid === "string") {
+        if (
+          event &&
+          event.type === "connection_registered" &&
+          typeof event.connectionUuid === "string"
+        ) {
           this.connectionUuid = event.connectionUuid;
+          this.activeRegistration =
+            typeof event.connectedAt === "string"
+              ? { connectionUuid: event.connectionUuid, connectedAt: event.connectedAt }
+              : null;
           try {
             this.onConnectionId(event.connectionUuid);
           } catch (err) {
@@ -305,4 +354,32 @@ export class SseListener {
       this.reconnectTimer = null;
     }
   }
+
+  /** @param {AbortController|null} abortController */
+  #refreshWatchdog(abortController) {
+    this.#clearWatchdog();
+    if (!abortController || abortController.signal.aborted || this.abortController !== abortController) return;
+    this.watchdogTimer = setTimeout(() => {
+      this.watchdogTimer = null;
+      if (
+        this.abortController !== abortController ||
+        abortController.signal.aborted ||
+        this.status !== "connected"
+      ) {
+        return;
+      }
+      this.logger.warn(
+        `[Chorus] SSE stream received no bytes for ${this.watchdogTimeoutMs}ms; reconnecting`
+      );
+      abortController.abort();
+      this.#scheduleReconnect();
+    }, this.watchdogTimeoutMs);
+  }
+
+  #clearWatchdog() {
+    if (this.watchdogTimer !== null) {
+      clearTimeout(this.watchdogTimer);
+      this.watchdogTimer = null;
+    }
+  }
 }