focus-guard 0.0.0-stage → 3.0.7

package/src/dsh/compactionWatch.mjs

@@ -0,0 +1,407 @@
+/**
+ * focus-guard 原生插件 · 压缩监察（2026-10-18）
+ *
+ * ── 为什么有这一层，而不是"再写一个压缩引擎" ────────────────────────────
+ * DSH 0.2 **自带**完整压缩栈，且当前会话就在用：
+ *   dsh-compaction（抽象缝 ctx.compaction）
+ *   + dsh-compaction-basic（后端，自动触发）
+ *   + dsh-command-compact（/compact）
+ *   + dsh-compaction-tool-result-pruner（超长工具结果剪枝）
+ * 挂载点在 preset 层：dsh-web-app/presets/cordis.patch.yml 的 cordis preset，
+ * host 平面则由 dsh-web-app/cordis.patch.yml 显式 disabled（压缩归 preset 所有）。
+ *
+ * 曾经存在的外部插件 DCR（local-dsh-memory-v09-live-extract）自建了一套压缩，
+ * 在 agent/pre-step 上 `agent.cancel` + `{kind:'reject'}`，抢在内置监听器之前把回合
+ * 打死在 step 0 —— 这才是 2026-10-18 那串 `CONTEXT_COMPACTION_REQUIRED` 的真根因。
+ * 内置阈值约 49k tokens 就触发，DCR 的 HARD 在 98k，内置本可早压。
+ *
+ * 结论：压缩由 DSH 负责，**FG 只负责监察**。
+ * 本模块的三条纪律：
+ *   ① 只读事件，绝不写 surface、绝不 append、绝不 cancel —— 它没有能力改变会话；
+ *   ② 只用事件里已经带着的事实（compactionId / shadowedSeqs / shadowedTokenCount /
+ *      usage.inputTokens / failure.code），**不猜模型上下文窗口**，不设自造阈值；
+ *   ③ 全部观察包在 try/catch 里，留痕失败只 warn —— 监察不能成为宿主的新故障点。
+ *
+ * ── 留痕口径 ───────────────────────────────────────────────────────────
+ * 走 audit.mjs 的统一入口 `appendAudit`（JSONL，与 deny / redline-exempt 同文件同格式）。
+ * 新增三个 action，纯增量，不改变既有记录的语义：
+ *   compaction           一次压缩落定（result: ok | failed）
+ *   compaction-anomaly   标记对异常（未闭合的 start / 无主的 end / id 不匹配）
+ *   context-overflow     请求撞上下文窗口 —— 这是"该压却没压"的唯一硬证据
+ *   compaction-watch-ready / compaction-watch-degraded
+ *                        进程级启动自证：本层是否真的挂上了两条缝。
+ *                        没有它，AUDIT.log 无法独立回答"监察层在不在"——
+ *                        只能靠 status.json 侧面推断，而 status.json 是心跳文件、不是审计台账。
+ *                        **同一状态每进程只报一次**；降级↔就位发生翻转时会再报一次（那是真实状态变化）。
+ *
+ * `compaction/prune`（工具结果剪枝）**不逐条留痕**：它按 8192 字符阈值频繁触发，
+ * 逐条写会把审计刷成流水账。改为只累计计数与释放 token，随 compaction / context-overflow
+ * 记录一并带出（prunes_so_far / pruned_tokens），既不丢信息也不淹没有效记录。
+ */
+
+import { appendAudit } from './audit.mjs'
+import { moduleSnapshot } from './heartbeat.mjs'
+
+const EV_START = 'compaction/start'
+const EV_END = 'compaction/end'
+const EV_PRUNE = 'compaction/prune'
+const EV_USER = 'user/message'
+const EV_ASSISTANT = 'assistant/message'
+
+/** 撞窗错误码，取自 @deepseek-ai/dsh-llm（lib/index.js:136 与 lib/types/error.js:22 同值）。 */
+export const CONTEXT_OVERFLOW_CODE = 'CONTEXT_WINDOW_EXCEEDED'
+
+/** 每会话监察状态。WeakMap 以 session 对象为键，会话释放即回收，不泄漏。 */
+const states = new WeakMap()
+
+/** 会话标识口径与 audit.mjs::sessionOf 一致：真实 id 在 session.id / session.header.id。 */
+function sessionIdOf(session) {
+  try {
+    const id = session?.id ?? session?.header?.id
+    if (typeof id === 'string' && id) return id
+  } catch {
+    /* header 是惰性 getter，取失败不致命 */
+  }
+  return 'dsh-native'
+}
+
+function stateFor(session) {
+  let state = states.get(session)
+  if (!state) {
+    state = {
+      sessionId: sessionIdOf(session),
+      open: null, // 未闭合的 compaction/start
+      compactions: 0,
+      failed: 0,
+      anomalies: 0,
+      prunes: 0,
+      prunedTokens: 0,
+      lastInputTokens: 0,
+      summary: null, // 本次压缩写下的替换消息（surfaceOp: replace）
+      overflowWarned: false,
+    }
+    states.set(session, state)
+  }
+  return state
+}
+
+/** 供自检 / 测试读取，不参与生产路径。 */
+export function _compactionWatchState(session) {
+  const state = states.get(session)
+  return state ? { ...state, open: state.open ? { ...state.open } : null, summary: state.summary ? { ...state.summary } : null } : null
+}
+
+function row(state, action, trigger, extra = {}) {
+  return {
+    ts: new Date().toISOString(),
+    session: state.sessionId,
+    action,
+    trigger,
+    level: null,
+    basis: 'builtin:compaction-basic',
+    ...extra,
+    pardon: false,
+  }
+}
+
+function clampText(value, max = 300) {
+  const text = typeof value === 'string' ? value : String(value ?? '')
+  return text.length > max ? text.slice(0, max) + '…' : text
+}
+
+/** 压缩落定留痕。 */
+function auditCompaction(state, { failed, durationMs, open, summary, error }) {
+  const parts = [
+    failed ? 'failed' : 'ok',
+    summary ? `${summary.shadowedNodes} 节点 seq ${summary.startSeq}..${summary.endSeq}` : '未观测到替换消息',
+    `${durationMs}ms`,
+    `输入 ${state.lastInputTokens}`,
+  ]
+  if (failed) parts.push(`error=${clampText(error, 120)}`)
+  appendAudit(
+    row(state, 'compaction', failed ? 'compaction/end(error)' : 'compaction/end', {
+      basis: open.sourceCommandId ? 'builtin:command-compact' : 'builtin:compaction-basic',
+      result: failed ? 'failed' : 'ok',
+      compaction_id: open.compactionId,
+      turn: open.turn,
+      source_command_id: open.sourceCommandId,
+      duration_ms: durationMs,
+      shadowed_nodes: summary ? summary.shadowedNodes : null,
+      shadowed_range: summary ? `${summary.startSeq}..${summary.endSeq}` : null,
+      input_tokens: state.lastInputTokens || null,
+      // 剪枝累计：不逐条留痕，但要让它随压缩记录一起可见（"释放了多少"）
+      prunes_so_far: state.prunes,
+      pruned_tokens: state.prunedTokens,
+      error: failed ? clampText(error, 300) : null,
+      evidence: clampText(parts.join(' | ')),
+    }),
+  )
+}
+
+/** 标记对异常留痕。0.2 用"未匹配的 start"作为 busy 信号，异常本身就是可诊断事实。 */
+function auditAnomaly(state, kind, detail) {
+  state.anomalies += 1
+  appendAudit(
+    row(state, 'compaction-anomaly', kind, {
+      detail: clampText(detail, 300),
+      evidence: clampText(`${kind}: ${detail}`),
+    }),
+  )
+}
+
+/**
+ * 观察一条会话事件。
+ * 纯函数式副作用：只更新本会话的监察状态并留痕，永不抛、永不改会话。
+ */
+function observe(session, event) {
+  if (!event || typeof event !== 'object') return
+  const type = event.type
+  if (type !== EV_START && type !== EV_END && type !== EV_PRUNE && type !== EV_USER && type !== EV_ASSISTANT) return
+
+  const state = stateFor(session)
+  const data = event.data && typeof event.data === 'object' ? event.data : {}
+
+  if (type === EV_START) {
+    if (state.open) {
+      auditAnomaly(
+        state,
+        'unmatched-start',
+        `上一次 start（id=${state.open.compactionId ?? '-'} seq=${state.open.seq}）未闭合就开始了 id=${data.compactionId ?? '-'}`,
+      )
+    }
+    state.open = {
+      compactionId: data.compactionId ?? null,
+      turn: data.turn ?? null,
+      // 手动 /compact 会带 sourceCommandId（见 dsh-compaction-basic compactSurfaceRegion），
+      // 据此区分"自动压缩"与"人类按需压缩"，审计里可分辨是谁触发的。
+      sourceCommandId: data.sourceCommandId ?? null,
+      seq: Number(event.seq) || 0,
+      at: Number(event.time) || Date.now(),
+    }
+    state.summary = null
+    return
+  }
+
+  if (type === EV_USER) {
+    // 压缩的摘要以 `user/message` + surfaceOp{op:'replace', startSeq, endSeq} 落在标记对之间。
+    const op = event.surfaceOp
+    if (state.open && op && typeof op === 'object' && op.op === 'replace') {
+      const sources = Array.isArray(event.sourceEventSeqs) ? event.sourceEventSeqs : []
+      state.summary = {
+        startSeq: op.startSeq ?? null,
+        endSeq: op.endSeq ?? null,
+        shadowedNodes: sources.length,
+      }
+    }
+    return
+  }
+
+  if (type === EV_END) {
+    const open = state.open
+    state.open = null
+    if (!open) {
+      auditAnomaly(state, 'orphan-end', `compaction/end（id=${data.compactionId ?? '-'}）没有对应的 start`)
+      state.summary = null
+      return
+    }
+    if (open.compactionId && data.compactionId && open.compactionId !== data.compactionId) {
+      auditAnomaly(state, 'mismatched-id', `start id=${open.compactionId} 对上了 end id=${data.compactionId}`)
+    }
+    const failed = data.error !== undefined
+    if (failed) state.failed += 1
+    else state.compactions += 1
+    auditCompaction(state, {
+      failed,
+      durationMs: Math.max(0, (Number(event.time) || Date.now()) - open.at),
+      open,
+      summary: state.summary,
+      error: data.error,
+    })
+    state.summary = null
+    return
+  }
+
+  if (type === EV_PRUNE) {
+    state.prunes += 1
+    state.prunedTokens += Number(data.shadowedTokenCount) || 0
+    return
+  }
+
+  // EV_ASSISTANT：记录本次请求的实际输入规模（供应商回报，非估算）
+  const input = Number(data?.usage?.inputTokens)
+  if (Number.isFinite(input) && input > 0) state.lastInputTokens = input
+}
+
+/**
+ * `session/event` 监听器工厂（普通事件，非 waterfall）。
+ * @param {{ warn: Function }} ctx 由 index.js 的 register() 注入
+ */
+export function compactionEventListener({ warn } = {}) {
+  // warn 缺失时退化为静默：catch 块里再抛一次，等于把监察变成新的 turn 杀手。
+  const emit = typeof warn === 'function' ? warn : () => {}
+  return (session, event) => {
+    try {
+      observe(session, event)
+    } catch (error) {
+      emit('压缩监察观察失败（不阻断会话）:', (error && error.message) || error)
+    }
+  }
+}
+
+/**
+ * `agent/request-error` 监听器工厂（**waterfall，必须始终 return next()**）。
+ *
+ * 撞窗是"该压却没压"的唯一硬证据——它由供应商拒绝给出，不需要 FG 猜任何阈值。
+ * 若此时本会话一次压缩、一次剪枝都没发生过，说明压缩栈根本没在干活，必须喊出来。
+ * @param {{ warn: Function }} ctx
+ */
+export function contextOverflowListener({ warn } = {}) {
+  const emit = typeof warn === 'function' ? warn : () => {}
+  return async ({ agent, failure }, next) => {
+    try {
+      if (failure && failure.code === CONTEXT_OVERFLOW_CODE) {
+        const session = agent && agent.session
+        if (session) {
+          const state = stateFor(session)
+          const dead = state.compactions === 0 && state.prunes === 0
+          appendAudit(
+            row(state, 'context-overflow', 'agent/request-error', {
+              code: failure.code,
+              input_tokens: state.lastInputTokens || null,
+              compactions_so_far: state.compactions,
+              failed_so_far: state.failed,
+              prunes_so_far: state.prunes,
+              pruned_tokens: state.prunedTokens,
+              stack_looks_dead: dead,
+              error: clampText(failure.message ?? failure.code, 300),
+              evidence: clampText(
+                `撞窗 code=${failure.code} 输入=${state.lastInputTokens || '-'} ` +
+                  `压缩=${state.compactions} 失败=${state.failed} 剪枝=${state.prunes}(${state.prunedTokens}tok)` +
+                  (dead ? ' —— 压缩栈疑似未生效' : ''),
+              ),
+            }),
+          )
+          if (dead && !state.overflowWarned) {
+            state.overflowWarned = true
+            emit(
+              `压缩监察：会话 ${state.sessionId} 撞上下文窗口，但本会话 0 次压缩 / 0 次剪枝 —— ` +
+                '内置压缩栈疑似未挂载（检查 preset 里的 compaction-basic 行）',
+            )
+          }
+        }
+      }
+    } catch (error) {
+      emit('压缩监察（撞窗）观察失败（不阻断会话）:', (error && error.message) || error)
+    }
+    // waterfall 纪律：无论观察到什么都必须放行，本模块没有拦截权。
+    return typeof next === 'function' ? next() : undefined
+  }
+}
+
+// ── 启动自证（2026-10-18，人类批示「让日志真正做到自证清白」）────────────────
+//
+// 病根：上面所有记录都是**被动**的——只有会话真的压过一次，AUDIT.log 里才有 `compaction`。
+// 于是"监察层没挂上"和"挂上了但还没触发"在日志里长得一模一样，都表现为"什么都没有"。
+// 唯一旁证是 `.focus-guard/status.json`，但那是心跳文件、随时被覆写，而且它证明的是
+// "插件在跳"，不是"这两条缝在听"。要把两者分开，只能在进程启动时无条件留一条。
+//
+// 口径：**同一状态每进程只报一次**（`announced` 闸门）；ready↔degraded 真发生翻转时再报一次
+// ——那不是重复，是真实的状态变化，必须留痕。翻转在当前装配流程里理论上不会发生
+// （register() 在 apply() 内同步跑完），闸门是防御性的，不是功能。
+
+/** 本层依赖的两条宿主缝；label 必须与 index.js 里 register() 的第三参数逐字一致。 */
+export const WATCH_SEAMS = ['session/event(compaction-watch)', 'agent/request-error(compaction-watch)']
+
+/** 进程启动时刻：只用于让"这条记录属于哪一次启动"可核对，不参与任何判断。 */
+const PROCESS_STARTED_AT = new Date().toISOString()
+
+/** @type {'ready'|'degraded'|null} 上一次宣告的状态；null = 本进程尚未宣告。 */
+let announced = null
+
+/** 测试钩子：清空宣告闸门，使同一进程内可重复验证。生产路径不调用。 */
+export function _resetWatchAnnounce() {
+  announced = null
+}
+
+/**
+ * 读当前装配快照，判定本层是否真的挂上了两条缝。
+ * 数据源是 heartbeat.mjs 的 MODULES —— register() 成功即 markModule(label, true)，
+ * 这是"注册到底成没成"的唯一权威口径，比任何自检代码更可信。
+ * @returns {{ ready: boolean, seams: Record<string,string>, bad: string[], ok: number, total: number, degraded: string[] }}
+ */
+function seamSnapshot() {
+  const snapshot = moduleSnapshot()
+  const seams = {}
+  const bad = []
+  for (const key of WATCH_SEAMS) {
+    // 未出现在快照里 = apply() 根本没跑到那行 register()，与 FAIL 同等对待。
+    const value = snapshot[key] === undefined ? 'MISSING: 未报到' : snapshot[key]
+    seams[key] = value
+    if (value !== 'OK') bad.push(`${key}=${value}`)
+  }
+  const keys = Object.keys(snapshot)
+  return {
+    ready: bad.length === 0,
+    seams,
+    bad,
+    ok: keys.filter((k) => snapshot[k] === 'OK').length,
+    total: keys.length,
+    // 全量降级清单：自证行要能独立说明"整机几成"，而不只是本层两条缝。
+    degraded: keys.filter((k) => snapshot[k] !== 'OK'),
+  }
+}
+
+/**
+ * 启动自证：把"监察层在不在"无条件写进 AUDIT.log 一次。
+ *
+ * 必须在 index.js 的两条 register() **与**心跳启动**之后**调用 ——
+ * 自证要反映的是最终装配结果，早一步调用就会漏掉心跳、报出错误的完成度。
+ *
+ * 永不抛：写不进去只 warn。自证失败不能变成宿主的新故障点（与本层其余部分同纪律）。
+ * @param {{ warn?: Function }} [options]
+ * @returns {'ready'|'degraded'|null} 本次宣告的状态；被闸门拦下时返回上次的状态
+ */
+export function announceWatchReady({ warn } = {}) {
+  const emit = typeof warn === 'function' ? warn : () => {}
+  try {
+    const { ready, seams, bad, ok, total, degraded } = seamSnapshot()
+    const next = ready ? 'ready' : 'degraded'
+    if (announced === next) return next
+    announced = next
+
+    const action = ready ? 'compaction-watch-ready' : 'compaction-watch-degraded'
+    const evidence = ready
+      ? `监察层就位：${WATCH_SEAMS.length} 条缝均已注册，压缩事件与撞窗告警都会进本日志` +
+        `（模块 ${ok}/${total} 报到，pid ${process.pid}）`
+      : `监察层未就位：${bad.join('；')} —— 该缝未注册时，对应的压缩事件不会进本日志` +
+        `（模块 ${ok}/${total} 报到，pid ${process.pid}）`
+
+    appendAudit({
+      ts: new Date().toISOString(),
+      // 进程级记录没有会话归属，用既有兜底口径 dsh-native，另以 scope 标明不是会话级留痕。
+      session: 'dsh-native',
+      action,
+      trigger: 'startup',
+      level: null,
+      basis: 'fg:compaction-watch',
+      scope: 'process',
+      pid: process.pid,
+      process_started_at: PROCESS_STARTED_AT,
+      watching: [...WATCH_SEAMS],
+      seams,
+      modules_ok: `${ok}/${total}`,
+      degraded_modules: degraded,
+      readonly: true,
+      evidence: clampText(evidence),
+      pardon: false,
+    })
+
+    if (!ready) {
+      emit(`压缩监察层未就位：${bad.join('；')} —— 这些缝未注册时，压缩事件不会进 AUDIT.log`)
+    }
+    return next
+  } catch (error) {
+    emit('压缩监察启动自证失败（不影响会话）:', (error && error.message) || error)
+    return null
+  }
+}

package/src/dsh/cordis.patch.yml

@@ -0,0 +1,10 @@
+# focus-guard 原生 Cordis 插件挂载（3.0.5 阶段一 · 最小可行原型）
+#
+# 安装：dsh plugin --profile <name> add <本仓库 packages/core 目录>
+# （bundle 补丁由 package.json 的 dsh.bundle.patch 指向本文件，随插件并入 profile 补丁层）
+#
+# ⚠ 与桥 @deepseek-ai/dsh-hooks-claude-code 互斥挂载（同一缝双监听=双跑，
+#   见仓库根 cordis.patch.yml 同源教训与《审 3 号报告》风险 4）。
+- insert:
+    - id: focus-guard-native
+      name: 'focus-guard'

package/src/dsh/heartbeat.mjs

@@ -0,0 +1,128 @@
+/**
+ * focus-guard 原生插件 · 心跳（2026-10-18）
+ *
+ * 目的只有一个：**宿主外**能判断 FG 还在不在跑。插件挂掉/被炸/卡死时，
+ * 文件不再更新，读文件的人立刻看得出来。
+ *
+ * 设计（与最初序列图一致，但去掉常驻 watchdog 进程）：
+ *   · 插件内定时器每 10s 原子覆写 `<仓库根>/.focus-guard/status.json`；
+ *   · 确认是按需的：`node src/dsh/status.mjs` 读文件算 lag，超 30s 判 STALE。
+ *
+ * 为什么不在插件里再跑一个轮询器：同进程的轮询器无法发现"本进程已死"，
+ * 只能发现"没在写"，等价于读文件本身。真 watchdog 必须是外部进程。
+ *
+ * 纪律：写入失败只 warn 一次，绝不抛出——心跳不能成为宿主的新故障点。
+ * 路径：与 AUDIT.log 同目录（`audit.mjs` 同一套 `../../../../` 上溯规则），
+ *      `FG_STATUS_FILE` 可重定向（测试必须用它，否则写进真实工作区）。
+ */
+
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 心跳周期；`FG_HEARTBEAT_INTERVAL_MS` 可覆盖（测试用）。 */
+export const HEARTBEAT_INTERVAL_MS = Number(process.env.FG_HEARTBEAT_INTERVAL_MS) || 10_000
+
+/** 超过该时长未更新即判 STALE；`FG_STALE_AFTER_MS` 可覆盖（测试用）。 */
+export const STALE_AFTER_MS = Number(process.env.FG_STALE_AFTER_MS) || 30_000
+
+/** 插件文件位于 <仓库根>/packages/core/src/dsh/ → 上溯 4 级到仓库根。 */
+export const STATUS_FILE = fileURLToPath(new URL('../../../../.focus-guard/status.json', import.meta.url))
+
+/** 心跳文件路径；与 `auditFilePath()` 同思路。 */
+export function statusFilePath() {
+  return process.env.FG_STATUS_FILE || STATUS_FILE
+}
+
+// ── 启动自检：各执法模块报到表（2026-10-18，人类批示「哪个模块没报告就喊」）──
+// 语义只有一条：`apply()` 里每个 `register()` 成功即报到，抛错即失败。
+// 未报到的模块＝该执法缝**可能没生效**，不能在降级状态下假装它在执法。
+
+/** @type {Map<string, { ok: boolean, error?: string, at: string }>} */
+const MODULES = new Map()
+
+/** 登记一个模块的启动结果。 */
+export function markModule(id, ok, error) {
+  MODULES.set(id, {
+    ok: ok === true,
+    ...(ok === true ? {} : { error: error === undefined ? '未报到' : String(error) }),
+    at: new Date().toISOString(),
+  })
+}
+
+/** 当前报到快照：{ 'id': 'OK' | 'FAIL: <msg>' }。 */
+export function moduleSnapshot() {
+  const out = {}
+  for (const [id, row] of MODULES) out[id] = row.ok ? 'OK' : `FAIL: ${row.error ?? '未报到'}`
+  return out
+}
+
+/** 未报到的模块 id 列表。 */
+export function degradedModules() {
+  return [...MODULES.entries()].filter(([, row]) => !row.ok).map(([id]) => id)
+}
+
+/**
+ * 模型侧告警文本；全部报到时返回 null（正常路径零注入）。
+ * 只在真的缺模块时占用系统提示 token。
+ */
+export function livenessNote() {
+  const bad = degradedModules()
+  if (bad.length === 0) return null
+  const detail = bad.map((id) => `${id}（${MODULES.get(id)?.error ?? '未报到'}）`).join('；')
+  return (
+    `[FG-DEGRADED] FocusGuard 启动自检：${MODULES.size - bad.length}/${MODULES.size} 个模块报到，` +
+    `缺失 ${bad.length} 个 —— ${detail}。` +
+    '这些缝的执法能力当前不可用，不要假设它们仍在拦；收尾时提示人类重启 DSH。'
+  )
+}
+
+/**
+ * 启动心跳：立即写一次，然后按周期覆写。返回停止函数。
+ * @param {{ warn?: (...parts: unknown[]) => void }} [options]
+ * @returns {() => void} 停止心跳
+ */
+export function startHeartbeat({ warn } = {}) {
+  const file = statusFilePath()
+  const startedAt = new Date().toISOString()
+  let warned = false
+
+  const beat = () => {
+    const body = {
+      status: 'ALIVE',
+      started_at: startedAt,
+      last_heartbeat: new Date().toISOString(),
+      pid: process.pid,
+      interval_ms: HEARTBEAT_INTERVAL_MS,
+      stale_after_ms: STALE_AFTER_MS,
+      // 启动自检结果随心跳一起对外：读文件的进程能同时看到「还在跳」和「哪些模块没报到」。
+      modules_ok: `${MODULES.size - degradedModules().length}/${MODULES.size}`,
+      degraded: degradedModules(),
+      modules: moduleSnapshot(),
+    }
+    try {
+      mkdirSync(dirname(file), { recursive: true })
+      // 先写临时文件再 rename：外部读到的永远是完整 JSON，不会是写了一半的截断内容。
+      const tmp = `${file}.tmp`
+      writeFileSync(tmp, `${JSON.stringify(body)}\n`)
+      renameSync(tmp, file)
+      warned = false
+    } catch (error) {
+      if (!warned) {
+        warned = true
+        warn?.('心跳写入失败（不阻断宿主）:', (error && error.message) || error)
+      }
+    }
+  }
+
+  // 首次写放到下一 tick：`startHeartbeat` 是自己也是最后一个报到模块，
+  // 同步写会让首帧快照少它一个（10/10 而不是 11/11），外面看到的就是错的完成度。
+  const kick = setTimeout(beat, 0)
+  const timer = setInterval(beat, HEARTBEAT_INTERVAL_MS)
+  // 心跳不该拖住宿主退出：unref 后它不参与事件循环引用计数。
+  if (typeof timer.unref === 'function') timer.unref()
+  return () => {
+    clearTimeout(kick)
+    clearInterval(timer)
+  }
+}