@a9i5k4/dsh-auto-memory 3.0.0 → 3.1.0

package/lib/python-sidecar-client.js

@@ -9,7 +9,19 @@
  *     错误 epoch/未知 requestId/重复或过期 response 全部计账丢弃,绝不注入上层。
  *   - 四种身份不混用:requestId(transport)/observationId(M5)/activationId(M6)/syncId(index)。
  *   - timeout/AbortSignal(cancel 通知)/latest-wins(由上层 M5 bridge 驱动)/crash recovery/circuit breaker。
- * 无 shell;无 HTTP;stdout 只进协议解析器;stderr 仅有界诊断。UTF-8 无 BOM。
+ *   - ★ #107 看门狗:连续超时(心跳缺失)达阈值 ⇒ **kill 旧进程 + 下次请求重生新进程**。旧实现
+ *     超时只发 cancel 通知、从不 kill ⇒ 挂死的 worker 永远无人收尸,后续每个请求各自等到超时。
+ *     stats 把「看门狗主动击杀」与「崩溃退出」分开记;熔断只由**终态成功**清零,段内进度帧
+ *     (index_sync_begin / index_sync_page)的 ack 成功不清零 —— 否则每个 Segment 一次 begin 就把
+ *     累计失败抹平,峰值恒 1、阈值 3 永不达,熔断形同虚设。
+ *   - ★ #108 stderr 可见:exit/fatal 分支把 stderr 尾部**原样**落一条 diag(同一次退出只记一条,
+ *     按行与字符双重截断防刷屏),并把截断后文本暴露为 stats.lastStderrTail /
+ *     debugView().lastStderrTail;同时保留 stderrTailBytes 以区分「确实没输出」与「输出被截」。
+ * 无 shell;无 HTTP;stdout 只进协议解析器;stderr 有界诊断 + 有界 diag 环形缓冲(不再只留字节数)。
+ * ★ 影响面纪律:本模块是「JS 语义默认 / Python 发烧友可选」里**Python 那一侧**的传输层,不参与
+ *   JS 语义路径;下述改动只影响 Python 档自身的行为,不改变 JS 端任何行为,也不让 python 侧的
+ *   存在或健康度成为 JS 语义生效的前提(未启动时零进程零 IO,调用方按需 lazy start)。
+ * UTF-8 无 BOM。
  */
 import { spawn } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
@@ -22,6 +34,31 @@ import {
 
 const B = M7_TRANSPORT_BUDGET_V1
 
+/**
+ * 看门狗/诊断策略(**客户端本地策略量**,刻意不放进 M7_TRANSPORT_BUDGET_V1)。
+ * 理由有二:①传输预算按契约冻结、变更须升协议版本,而「多久判挂死」是客户端自愈策略、不是 wire 契约;
+ * ②wire 文件同期另有 PR(#122/#124)在改,本任务不去碰它以避开写域冲突。
+ */
+const SIDECAR_WATCHDOG_V1 = Object.freeze({
+  stallThreshold: 3,      // 连续超时(心跳缺失)达此数 ⇒ 判定挂死,看门狗击杀旧进程
+  stderrTailChars: 4096,  // stderr 环形尾部保留长度(既有语义,原为字面量 4096)
+  diagRingCapacity: 16,   // diag 环形缓冲条数(超出丢最旧)
+  diagTailLines: 8,       // 单条 diag 最多保留的 stderr 行数(防刷屏)
+  diagTailChars: 1200,    // 单条 diag 最多保留的 stderr 字符数
+})
+
+/** 退出归因优先级:高优先级不被低优先级覆盖。 */
+const EXIT_KIND_RANK_V1 = Object.freeze({ crash: 0, restart: 1, dispose: 1, fatal: 2, watchdog: 3 })
+
+/**
+ * ★ #107 熔断清零口径:只有「终态成功」才把累计失败清零。
+ * index_sync_begin / index_sync_page 是**段内进度帧**(每个 Segment 都会 begin 一次),它们的 ack
+ * 成功只证明 worker 读到并回了一行,不能证明它健康。旧实现无差别清零 ⇒ 每个 Segment 的 begin 一经
+ * 成功就把累计失败抹平,峰值恒 1、阈值 3(breakerFailureThreshold)永不达,熔断形同虚设。
+ * health / context_push / index_sync_commit 才是各自工作单元的终态应答。
+ */
+const TERMINAL_SUCCESS_TYPES_V1 = new Set(['health', 'context_push', 'index_sync_commit'])
+
 /** 捆绑 fake worker 的默认绝对路径(python/worker_v1.py)。 */
 export function defaultWorkerScriptPathPre() {
   try {
@@ -53,6 +90,19 @@ export function createPythonSidecarClientPre(opts = {}) {
   const seenActivationIdSet = new Set()
   let writeChain = Promise.resolve()
   let lastSentFrame = null
+  // ---- #107 看门狗 / #108 stderr 可见:状态 ----
+  let genSeq = 0                       // 世系序号发生器
+  let generation = 0                   // 当前世系号(0 = 从未启动过)
+  let consecutiveTimeouts = 0          // 连续超时(心跳缺失)计数
+  let halfOpenPending = false          // 熔断冷却到期后待用 health() 探活
+  let respawnPending = false           // 看门狗击杀后待重生(下次 spawn 计一次 watchdog.respawns)
+  let lastStderr = { tail: '', bytes: 0, truncated: false, at: 0, generation: 0, totalLines: 0, keptLines: 0 }
+  let lastExitDiagKey = ''             // 「同一次退出只记一条」去重键 = 世系号 + 退出种类
+  let lastExitDiagRef = null           // 该条 diag 记录引用(供 exit 之后迟到的 stderr 就地刷新)
+  let lastExitGen = 0                  // 最近一次退出的世系号
+  const genOfProc = new WeakMap()      // ChildProcess -> 世系号
+  const exitKindByGen = new Map()      // 世系号 -> 退出种类(crash/restart/dispose/fatal/watchdog)
+  const diagRing = []                  // 有界 diag 环形缓冲(给人看的诊断,含中文归因)
   const breaker = { consecutiveFailures: 0, openUntil: 0 }
   const stats = {
     starts: 0, exits: 0, framesIn: 0, requests: 0, succeeded: 0, activationsReceived: 0,
@@ -60,6 +110,17 @@ export function createPythonSidecarClientPre(opts = {}) {
     dropped: { badJson: 0, badEnvelope: 0, staleEpoch: 0, unknownRequest: 0, typeMismatch: 0, duplicateActivation: 0 },
     failed: { timeout: 0, crashed: 0, aborted: 0, circuitOpen: 0, unavailable: 0, backpressure: 0, protocol: 0, workerError: 0, disposed: 0 },
     lastExit: null, lastFatal: null,
+    // ★ #107 看门狗:把「主动重启」与「崩溃退出」分开记,不再混在一个 exits 计数里。
+    watchdog: { kills: 0, respawns: 0, lastReason: null, lastAt: 0, lastDetail: null },
+    exitKinds: { crash: 0, restart: 0, dispose: 0, fatal: 0, watchdog: 0, spawnError: 0 },
+    breakerProbes: { attempted: 0, ok: 0, failed: 0 },
+    lastExitNote: null,
+    // ★ #108 stderr:lastStderrTail 是**截断后可读文本**(不再只有字节数);
+    //   stderrTailBytes 仍在 debugView 上,用来区分「没输出」与「输出被截」。
+    lastStderrTail: '',
+    lastStderrTailBytes: 0,
+    lastStderrTailTruncated: false,
+    lastStderrTailAt: 0,
   }
 
   function resolveOpt(k) { return opt(k, null) }
@@ -75,14 +136,170 @@ export function createPythonSidecarClientPre(opts = {}) {
 
   function breakerOpen() { return Date.now() < breaker.openUntil }
 
+  // ============ #107 看门狗 / #108 stderr 可见:诊断与自愈 ============
+  // 说明:以下全部只服务 Python 侧车自身的自愈与可观测性,不参与 JS 语义路径。
+
+  /** 有界 diag 环形缓冲:落一条**给人看**的中文诊断;opts.onDiag 在场时同步外发一份。 */
+  function pushDiag(level, text) {
+    const rec = { at: Date.now(), level, sidecar: 'python-sidecar-pre', generation, message: String(text) }
+    diagRing.push(rec)
+    while (diagRing.length > Math.max(1, Number(opt('diagRingCapacity', SIDECAR_WATCHDOG_V1.diagRingCapacity)))) diagRing.shift()
+    const sink = resolveOpt('onDiag')
+    if (typeof sink === 'function') { try { sink({ at: rec.at, level: rec.level, generation, message: rec.message }) } catch (_) {} }
+    return rec
+  }
+
+  /**
+   * 把 stderr 尾部整理成可读文本:保留尾 N 行(默认 8)且不超过 M 字符(默认 1200)。
+   * 被截断时在正文前留一行说明 —— 避免读者误以为「这就是全部输出」。
+   */
+  function tailForDiag(raw) {
+    const NL = String.fromCharCode(10)
+    const CR = String.fromCharCode(13)
+    const src = String(raw == null ? '' : raw)
+    const bytes = src.length
+    // 刻意不用正则字面量:本仓所有 .js 均为 CRLF,避免任何转义歧义。
+    const all = src.split(NL).map((l) => (l.endsWith(CR) ? l.slice(0, -1) : l))
+    while (all.length && all[all.length - 1] === '') all.pop()
+    const maxLines = Math.max(1, Number(opt('diagTailLines', SIDECAR_WATCHDOG_V1.diagTailLines)))
+    const maxChars = Math.max(1, Number(opt('diagTailChars', SIDECAR_WATCHDOG_V1.diagTailChars)))
+    const kept = all.slice(-maxLines)
+    let truncated = kept.length < all.length
+    let text = kept.join(NL)
+    if (text.length > maxChars) { text = text.slice(-maxChars); truncated = true }
+    const head = truncated ? '…[已按行/字符截断,下面不是全部输出]…' + NL : ''
+    return { text: head + text, truncated, keptLines: kept.length, totalLines: all.length, bytes }
+  }
+
+  /** 退出归因中文说明(回答「哪一侧车、哪一代、怎么退的、退出码多少」)。 */
+  function humanExitNote(gen, kind, code, signalName) {
+    const why = kind === 'watchdog' ? '被看门狗主动击杀(连续超时=心跳缺失达阈值,判定挂死)'
+      : kind === 'fatal' ? '因协议致命错误被就地击杀(帧纪律违规)'
+        : kind === 'restart' ? '被 restart() 主动重启(刻意换代,不是故障)'
+          : kind === 'dispose' ? '随 dispose() 收尾关闭(刻意关闭,不是故障)'
+            : '自行退出(非看门狗击杀)——即「崩溃退出」'
+    const c = (code === null || code === undefined) ? 'null' : String(code)
+    const s = signalName ? String(signalName) : 'null'
+    return '第 ' + gen + ' 代 Python 语义侧车' + why + ':退出码 code=' + c + ',signal=' + s
+  }
+
+  /** 退出归因写入(优先级 watchdog > fatal > dispose/restart > crash;低优先级不覆盖高优先级)。 */
+  function markExitKind(gen, kind) {
+    if (!gen) return
+    const cur = exitKindByGen.get(gen) || 'crash'
+    if ((EXIT_KIND_RANK_V1[kind] || 0) < (EXIT_KIND_RANK_V1[cur] || 0)) return
+    exitKindByGen.set(gen, kind)
+    while (exitKindByGen.size > 64) exitKindByGen.delete(exitKindByGen.keys().next().value)
+  }
+
+  /**
+   * ★ #108 关键修复:把 stderr 尾部**原样**落一条 diag。
+   * 旧实现只把 4KB 尾部收进 `stderrTail` 变量、对外仅暴露 `stderrTailBytes` 一个整数,
+   * **内容没有任何读者** ⇒ Python traceback 永远看不到,用户只能看到「字节数非 0」。
+   * 同一次退出只记一条:以「世系号 + 退出种类」为键,命中则**就地刷新**(退出之后 stdio 往往
+   * 还在排空,close 晚于 exit、尾字节会迟到;就地刷新既补全内容又不新开第二条)。
+   */
+  function logExitDiag(gen, kind, reasonText) {
+    const t = tailForDiag(stderrTail)
+    lastStderr = { tail: t.text, bytes: t.bytes, truncated: t.truncated, at: Date.now(), generation: gen, totalLines: t.totalLines, keptLines: t.keptLines }
+    stats.lastStderrTail = t.text
+    stats.lastStderrTailBytes = t.bytes
+    stats.lastStderrTailTruncated = t.truncated
+    stats.lastStderrTailAt = lastStderr.at
+    const note = t.bytes === 0
+      ? 'stderr 零输出(确实没打印,不是被截断)'
+      : (t.truncated
+        ? 'stderr 尾部累计 ' + t.bytes + ' 字符 / ' + t.totalLines + ' 行,此处只保留最后 ' + t.keptLines + ' 行共 ' + t.text.length + ' 字符(已按行与字符双重截断,防刷屏)'
+        : 'stderr 尾部累计 ' + t.bytes + ' 字符 / ' + t.totalLines + ' 行,已全部保留')
+    const NL = String.fromCharCode(10)
+    const body = String(reasonText) + ';' + note + (t.text ? NL + '—— stderr 原文 ——' + NL + t.text : '')
+    const key = gen + ':' + kind
+    const level = (kind === 'crash' || kind === 'watchdog' || kind === 'fatal') ? 'error' : 'info'
+    if (lastExitDiagKey === key && lastExitDiagRef) {
+      lastExitDiagRef.message = body
+      lastExitDiagRef.at = lastStderr.at
+      lastExitDiagRef.level = level
+      return lastExitDiagRef
+    }
+    lastExitDiagKey = key
+    lastExitGen = gen
+    lastExitDiagRef = pushDiag(level, body)
+    return lastExitDiagRef
+  }
+
+  /**
+   * ★ #107 看门狗:判定侧车挂死 ⇒ **kill 旧进程 + 下次请求重生新进程**。
+   * 旧实现在超时分支只 `notify('cancel')`、从不 kill ⇒ 挂死的 worker 永远无人收尸,后续每个
+   * 请求各自等到自己的超时、再各自发一条无用的 cancel;对用户的表现是「Python 档语义静默失效」。
+   * 刻意不在此处立即 spawn:避免在熔断打开期制造进程(既有套件断言「打开期零 spawn」);
+   * 重建交给下一次 ensureStarted() —— 那里必然带新 epoch,index 重同步也随之触发。
+   */
+  function disarmHungChild(trigger, detail) {
+    const proc = child
+    consecutiveTimeouts = 0
+    if (!proc) return
+    markExitKind(generation, 'watchdog')
+    child = null
+    epoch = null
+    buffer = Buffer.alloc(0)
+    respawnPending = true
+    stats.watchdog.kills++
+    stats.watchdog.lastReason = trigger
+    stats.watchdog.lastAt = Date.now()
+    stats.watchdog.lastDetail = detail || null
+    const thr = Math.max(1, Number(opt('watchdogStallThreshold', SIDECAR_WATCHDOG_V1.stallThreshold)))
+    pushDiag('error', '第 ' + generation + ' 代 Python 语义侧车连续 ' + thr + ' 次心跳缺失(' + trigger + ')⇒ 看门狗主动击杀旧进程;下次请求将重生新进程(新 epoch),未经确认的旧 in-flight 请求按 crashed 结算。')
+    logExitDiag(generation, 'watchdog', humanExitNote(generation, 'watchdog', null, null))
+    try { proc.stdin.destroy() } catch (_) {}
+    try { proc.kill() } catch (_) {}
+    rejectAll('crashed')
+  }
+
+  /** 心跳缺失证据:只把「超时」算挂死(abort 是调用方主动取消,不构成挂死证据)。 */
+  function noteStall(type, requestId, timeoutMs) {
+    consecutiveTimeouts++
+    const thr = Math.max(1, Number(opt('watchdogStallThreshold', SIDECAR_WATCHDOG_V1.stallThreshold)))
+    if (consecutiveTimeouts < thr) return
+    disarmHungChild('连续超时', { type: String(type), requestId: String(requestId), timeoutMs: Number(timeoutMs), consecutiveTimeouts })
+  }
+
+  /**
+   * ★ #107 熔断半开探测:冷却到期后不放行盲发,先用 health()(有界)自证 worker 活着再放行。
+   * 这是 health() 在仓内的**唯一真实调用点**。type==='health' 不入此分支 ⇒ 不会递归,
+   * 也不会把探针自身的失败再算作一次新的挂死证据。
+   */
+  async function probeThenSend(type, payload, rOpts) {
+    halfOpenPending = false
+    stats.breakerProbes.attempted++
+    const probeTimeout = Math.min(Math.max(1, Number(opt('requestTimeoutMs', B.requestTimeoutMs))), 2000)
+    const probe = await request('health', {}, { timeoutMs: probeTimeout })
+    if (probe && probe.ok) {
+      stats.breakerProbes.ok++
+      breaker.consecutiveFailures = 0
+      consecutiveTimeouts = 0
+      return request(type, payload, rOpts)
+    }
+    stats.breakerProbes.failed++
+    breaker.openUntil = Date.now() + Number(opt('breakerCooldownMs', B.breakerCooldownMs))
+    halfOpenPending = true
+    stats.failed.circuitOpen++
+    pushDiag('error', '熔断半开探测未通过:Python 语义侧车 health 探针返回 ' + String((probe && probe.code) || 'unknown') + ' ⇒ 重新打开熔断 ' + Number(opt('breakerCooldownMs', B.breakerCooldownMs)) + 'ms;本次请求按 circuit-open 返回。')
+    return { ok: false, code: 'circuit-open', retryInMs: breaker.openUntil - Date.now() }
+  }
+
   /** lazy start:no-shell spawn;仅由显式启用的调用路径触达。 */
   function ensureStarted() {
     if (disposed) return { ok: false, code: 'disposed' }
     if (child && (child.killed || (child.stdin && child.stdin.destroyed))) {
       // 上一个进程正在收尾(exit 事件未到):按已死处理,允许立即重生
+      // ★ issue #72 修复（2026-09-19）：此处必须**同时清空共享 buffer**。
+      //   旧实现只置 `epoch = null`（等 `:121` 的 exit 事件去清 buffer），但这条分支的前提正是
+      //   **exit 尚未到达** ⇒ 旧 worker 残留在 `buffer` 里的**无换行尾字节**会被新 worker 的首帧
+      //   `concat` 进去 ⇒ 该行 badJson ⇒ 应答被吞、请求白等到超时（默认 5000ms）。
       try { child.kill() } catch (_) {}
       child = null
       epoch = null
+      buffer = Buffer.alloc(0)   // ★ 丢弃旧代残尾,避免污染新 worker 首帧
     }
     if (child) return { ok: true }
     const scriptPath = String(resolveOpt('scriptPath') || defaultWorkerScriptPathPre())
@@ -101,9 +318,16 @@ export function createPythonSidecarClientPre(opts = {}) {
     }
     child = proc
     stats.starts++
+    generation = ++genSeq
+    genOfProc.set(proc, generation)
+    exitKindByGen.set(generation, 'crash')
+    stderrTail = ''          // ★ #108:stderr 尾部按**世系**隔离,避免把上代 traceback 误挂到本代
+    consecutiveTimeouts = 0
+    if (respawnPending) { stats.watchdog.respawns++; respawnPending = false }
     proc.stdout.on('data', (chunk) => { try { feed(chunk) } catch (_) { fatal('protocol') } })
     proc.stderr.on('data', (chunk) => {
-      stderrTail = (stderrTail + chunk.toString('utf8')).slice(-4096)
+      stderrTail = (stderrTail + chunk.toString('utf8'))
+        .slice(-Math.max(256, Number(opt('stderrTailChars', SIDECAR_WATCHDOG_V1.stderrTailChars))))
     })
     proc.on('error', () => {
       // spawn 失败(ENOENT 等):结构化失败,不计崩溃重启
@@ -115,12 +339,19 @@ export function createPythonSidecarClientPre(opts = {}) {
       noteFailure('unavailable')
     })
     proc.on('exit', (code, signalName) => {
+      const gen = genOfProc.get(proc) || 0
+      const kind = exitKindByGen.get(gen) || 'crash'
+      // ★ #107:无论是否当前世系都先记账 —— 「哪一侧车、第几代、怎么退的、退出码多少」
+      //   stats.exits 仍是总退出数;active 的归因细分在 stats.exitKinds。
+      stats.exits++
+      stats.exitKinds[kind] = (stats.exitKinds[kind] || 0) + 1
+      stats.lastExit = { code, signal: signalName, generation: gen, kind }
+      stats.lastExitNote = humanExitNote(gen, kind, code, signalName)
+      logExitDiag(gen, kind, stats.lastExitNote)
       if (child !== proc) return
       child = null
       epoch = null
       buffer = Buffer.alloc(0)
-      stats.exits++
-      stats.lastExit = { code, signal: signalName }
       rejectAll('crashed')
     })
     return { ok: true }
@@ -128,13 +359,21 @@ export function createPythonSidecarClientPre(opts = {}) {
 
   function rejectAll(code) {
     for (const [, entry] of pending) settle(entry, { ok: false, code })
-    noteFailure(code)
+    // ★ #107:不再在循环外额外 noteFailure(code) —— settle() 已按每个失败请求各计一次,
+    //   旧实现在此重复计数 ⇒ 崩溃时挂 K 个请求会被算成 K+1 次失败,熔断阈值提前触发(假熔断)。
   }
 
   function fatal(kind) {
     stats.lastFatal = kind
     buffer = Buffer.alloc(0) // 丢弃残留半帧,防止污染重生进程的解析流
-    if (child) { try { child.stdin.destroy() } catch (_) {} try { child.kill() } catch (_) {} }
+    // ★ #108:致命分支同样把 stderr 尾部原样落一条 diag;与随后 exit 同键(世系号+fatal)
+    //   ⇒ 同一次退出只记一条。
+    logExitDiag(generation, 'fatal', humanExitNote(generation, 'fatal', null, null) + ' 触发原因=' + String(kind))
+    if (child) {
+      markExitKind(generation, 'fatal')
+      try { child.stdin.destroy() } catch (_) {}
+      try { child.kill() } catch (_) {}
+    }
     rejectAll('protocol')
   }
 
@@ -161,7 +400,16 @@ export function createPythonSidecarClientPre(opts = {}) {
     const v = validateTransportFramePre(obj, { direction: 'in' })
     if (!v.ok) { stats.dropped.badEnvelope++; return }
     const frame = v.frame
-    if (epoch !== null && frame.workerEpoch !== epoch) { stats.dropped.staleEpoch++; return }
+    // ★ issue #72 修复（2026-09-19）：把入站 epoch 门从 **fail-open 改为 fail-closed**，与文件头 :7 的承诺一致。
+    //   旧写法 `if (epoch !== null && frame.workerEpoch !== epoch)`：**`epoch === null` 时整条门失效**，
+    //   任何合法 envelope 的帧都会穿透到 handler。epoch 为 null 的窗口是真实存在的
+    //   （未启动 / `exit` 事件已置 null 但旧 stdio 尚未排空 / restart 后到新 spawn 之间），
+    //   而 `activation_request` 上游 `context-host` **无二次校验**（同 activationId 有 dedup 兜底，
+    //   但**新 activationId 可穿透**）⇒ 幽灵激活。
+    //   新判据：**epoch 为空 ⇒ 一律丢弃**。理由：spawn 时同步赋 epoch（:91 `epoch = 'wk_' + …` 在
+    //   `spawn()` **之前**执行），出站帧也就带上了 epoch；对端 worker 以 `--expect-epoch` 自证身份后才回帧
+    //   ⇒ **正常路径不存在"帧先于 epoch"**，丢弃不会误伤任何合法流量。
+    if (!epoch || frame.workerEpoch !== epoch) { stats.dropped.staleEpoch++; return }
     if (frame.type === 'activation_request') {
       const activation = frame.payload && frame.payload.activation
       const aid = activation && activation.activationId
@@ -194,7 +442,17 @@ export function createPythonSidecarClientPre(opts = {}) {
     if (entry.timer) clearTimeout(entry.timer)
     if (entry.onAbort) { try { entry.signal.removeEventListener('abort', entry.onAbort) } catch (_) {} }
     pending.delete(entry.requestId)
-    if (result.ok) { stats.succeeded++; breaker.consecutiveFailures = 0 }
+    if (result.ok) {
+      stats.succeeded++
+      // ★ #107 熔断清零口径:只有「终态成功」清零累计失败;段内进度帧(index_sync_begin /
+      //   index_sync_page)的 ack 成功**不清零** —— 否则每个 Segment 一次 begin 就把累计失败
+      //   抹平,峰值恒 1、阈值 3 永不达,熔断形同虚设。
+      if (TERMINAL_SUCCESS_TYPES_V1.has(entry.type)) {
+        breaker.consecutiveFailures = 0
+        consecutiveTimeouts = 0
+        halfOpenPending = false
+      }
+    }
     else {
       const bucket = stats.failed[result.code]
       if (bucket === undefined) stats.failed.protocol++
@@ -208,9 +466,18 @@ export function createPythonSidecarClientPre(opts = {}) {
     lastSentFrame = frame
     if (!child || !child.stdin || child.stdin.destroyed) return false
     const line = Buffer.from(JSON.stringify(frame) + '\n', 'utf8')
+    // ★ issue #75 CC-9 修复（2026-09-19）：**建帧时捕获当时的 child 引用**，flush 时校验身份。
+    //   旧实现：`writeChain.then(...)` 回调里解引用**当时的**模块级 `child` 变量。
+    //   若 writeChain 排队期间发生 respawn（`ensureStarted` 的收尾中重生 / `restart()`），
+    //   回调会读到**新** child，把**旧 epoch 的帧**写进新 worker 的 stdin ⇒ 对端回帧 epoch-mismatch
+    //   ⇒ 被判 `staleEpoch` 丢弃 ⇒ 该请求挂满自身超时（默认 5000ms）。
+    //   现改为闭包捕获 `sentTo`，且 flush 时 `child !== sentTo` 即视为该帧已随旧进程作废。
+    const sentTo = child
+    const sentStdin = child.stdin
     writeChain = writeChain.then(() => new Promise((done) => {
-      if (!child || !child.stdin || child.stdin.destroyed) { done(); return }
-      child.stdin.write(line, () => done())
+      if (child !== sentTo) { done(); return }   // 已换代：本帧作废，不得写入新 worker
+      if (!sentStdin || sentStdin.destroyed) { done(); return }
+      sentStdin.write(line, () => done())
     }))
     writeChain = writeChain.catch(() => {})
     return true
@@ -227,6 +494,19 @@ export function createPythonSidecarClientPre(opts = {}) {
       stats.failed.circuitOpen++
       return Promise.resolve({ ok: false, code: 'circuit-open', retryInMs: breaker.openUntil - Date.now() })
     }
+    // ★ #107 熔断半开探测:冷却到期后不放行盲发,先用 health()(有界)自证 worker 活着再放行。
+    //   这是 health() 在仓内的**唯一真实调用点** —— 旧实现 health() 全仓零调用,文件里那句
+    //   「health 探针(breaker half-open 用;有界响应)」是空头承诺。type==='health' 不入此分支
+    //   ⇒ 不会递归,也不会把探针本身的失败再算作一次挂死证据。
+    if (halfOpenPending && type !== 'health') return probeThenSend(type, payload, rOpts)
+    return sendNow(type, payload, rOpts)
+  }
+
+  /**
+   * 真正的建帧 + 入队。与旧 request() 同体,刻意保持「调用后同步可见 _lastFrameForTest()」
+   * 的既有契约(既有套件靠它在 await 之前做帧级断言)。
+   */
+  function sendNow(type, payload, rOpts = {}) {
     const started = ensureStarted()
     if (!started.ok) {
       stats.failed[started.code] = (stats.failed[started.code] || 0) + 1
@@ -239,7 +519,7 @@ export function createPythonSidecarClientPre(opts = {}) {
     const mf = makeRequestFramePre({ type, payload, requestId, workerEpoch: epoch, sentAt })
     if (!mf.ok) { stats.failed.protocol++; return Promise.resolve({ ok: false, code: 'protocol', reason: mf.reason }) }
     return new Promise((resolve) => {
-      const entry = { requestId, expectedType: RESPONSE_TYPE_FOR_V1[type], resolve, settled: false, timer: null, signal: rOpts.signal || null, onAbort: null }
+      const entry = { requestId, type, expectedType: RESPONSE_TYPE_FOR_V1[type], resolve, settled: false, timer: null, signal: rOpts.signal || null, onAbort: null }
       pending.set(requestId, entry)
       stats.requests++
       const written = writeFrame(mf.frame)
@@ -248,6 +528,9 @@ export function createPythonSidecarClientPre(opts = {}) {
       entry.timer = setTimeout(() => {
         settle(entry, { ok: false, code: 'timeout', timeoutMs })
         notify('cancel', { requestId })
+        // ★ #107:旧实现到此为止(只发 cancel,不 kill)⇒ 挂死的 worker 无人收尸。
+        //   这里补上心跳缺失证据的累计与看门狗收尸(达阈值才动,避免偶发慢帧被误杀)。
+        noteStall(type, requestId, timeoutMs)
       }, timeoutMs)
       if (entry.signal) {
         if (entry.signal.aborted) {
@@ -282,7 +565,14 @@ export function createPythonSidecarClientPre(opts = {}) {
     if (child) { try { child.kill() } catch (_) {} }
     child = null
     epoch = null
+    // ★ issue #72 修复：restart 同样要清 buffer（kill 后 exit 事件可能滞后，
+    //   旧代残尾会污染新 worker 首帧 ⇒ 该行 badJson ⇒ 请求白等到超时）。
+    buffer = Buffer.alloc(0)
     stats.restarts++
+    markExitKind(generation, 'restart')
+    breaker.consecutiveFailures = 0
+    consecutiveTimeouts = 0
+    pushDiag('info', 'restart() 主动重启 Python 语义侧车:旧进程已击杀、新 epoch 待下次请求重生(原因:' + String(reason === undefined || reason === null ? '未给' : reason) + ')。')
     void reason
   }
 
@@ -296,7 +586,18 @@ export function createPythonSidecarClientPre(opts = {}) {
       epoch: epoch ? epoch.slice(0, 12) + '…' : null,
       pending: pending.size,
       breaker: { open: breakerOpen(), consecutiveFailures: breaker.consecutiveFailures, cooldownMs: Number(opt('breakerCooldownMs', B.breakerCooldownMs)) },
+      generation,
+      // ★ #108:stderrTailBytes 保留原语义(当前世系累计保留的尾部长度)——0 表示确实没输出,
+      //   非 0 且 lastStderrTailTruncated=true 表示有输出但被截断。文本本体见 lastStderrTail。
       stderrTailBytes: stderrTail.length,
+      lastStderrTail: lastStderr.tail,
+      lastStderrTailBytes: lastStderr.bytes,
+      lastStderrTailTruncated: lastStderr.truncated,
+      lastStderrTailAt: lastStderr.at,
+      consecutiveTimeouts,
+      halfOpenProbePending: halfOpenPending,
+      watchdog: JSON.parse(JSON.stringify(stats.watchdog)),
+      recentDiag: diagRing.slice(-4).map((d) => ({ at: d.at, level: d.level, message: d.message })),
       stats: JSON.parse(JSON.stringify(stats)),
     }
   }
@@ -304,6 +605,7 @@ export function createPythonSidecarClientPre(opts = {}) {
   function dispose(reason) {
     if (disposed) return
     disposed = true
+    markExitKind(generation, 'dispose')
     if (child) { try { child.kill() } catch (_) {} }
     child = null
     epoch = null
@@ -322,5 +624,6 @@ export function createPythonSidecarClientPre(opts = {}) {
     onActivation(handler) { activationHandlers.add(handler); return () => activationHandlers.delete(handler) },
     _statsForTest: stats,
     _pendingForTest: pending,
+    _diagRingForTest: diagRing,
   }
 }

package/lib/recall-fusion.js

@@ -21,6 +21,19 @@ export const FUSION_RRF_K_V1 = 60
 /** rank 尺度常数:rank/divisor 把秩归到 (0,1] 量级(默认与 k 同值)。 */
 export const FUSION_RRF_DIVISOR_V1 = 60
 
+/**
+ * ★M2.5b：层次优先级序（与注入侧一致）。
+ *
+ * 出处：`tier-layer-inject.js:58 TIER_LAYER_ORDER_V1` —— **必须与之逐字相同**。
+ *
+ * 为什么不直接 import：本模块头注释承诺「**零依赖**、纯函数、零 IO」，
+ *   引入跨模块依赖会破坏该契约（且 tier-layer-inject 自身还有依赖链）。
+ * 为了既不破契约、又不产生「双源漂移」，此处**本地复刻**并由测试**断言两者相等**
+ *   （见 smoke-test-m25b-layer-arm-pre.mjs 的「常量一致性」断言）——
+ *   任何一侧改动而另一侧未同步，测试立刻红。
+ */
+export const FUSION_LAYER_ORDER_V1 = Object.freeze(['project', 'whiteboard', 'user', 'reflection', 'log'])
+
 /** 版本标识。 */
 export const RECALL_FUSION_VERSION = 'rrf_fusion_v1'
 
@@ -45,20 +58,63 @@ export function rankFusionRRFPre(pairs, opts = {}) {
   const list = Array.isArray(pairs) ? pairs.filter((p) => p && typeof p.memoryId === 'string') : []
 
   // 每臂独立排名:非空有限值按分数降序(平局 memoryId 升序)取秩(1 起);缺席者无秩。
-  const rankArm = (key) => {
+  // ★M2.5b：新增 `strMode` —— 层次臂的值是**字符串**，默认的「只收有限数」过滤会把它全部滤掉
+  //   （实测踩坑：layer 臂曾因此静默恒为 0，套件 [3] 抓到）。strMode=true 时接受非空字符串。
+  const rankArm = (key, cmp, strMode) => {
     const entries = []
     for (const p of list) {
       const v = p[key]
-      if (typeof v === 'number' && Number.isFinite(v)) entries.push({ memoryId: p.memoryId, v })
+      if (strMode) {
+        if (typeof v === 'string' && v) entries.push({ memoryId: p.memoryId, v })
+      } else if (typeof v === 'number' && Number.isFinite(v)) {
+        entries.push({ memoryId: p.memoryId, v })
+      }
     }
-    entries.sort((a, b) => (b.v !== a.v ? b.v - a.v : (a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0)))
+    const tie = (a, b) => (a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0)
+    entries.sort(cmp || ((a, b) => (b.v !== a.v ? b.v - a.v : tie(a, b))))
     const ranks = new Map()
     entries.forEach((e, i) => ranks.set(e.memoryId, i + 1))
     return ranks
   }
+
+  /**
+   * ★M2.5b：层次臂的**序** = 注入侧的层次优先级序（二者必须一致）。
+   * 出处：`tier-layer-inject.js:58 TIER_LAYER_ORDER_V1`
+   *       = ['project','whiteboard','user','reflection','log']。
+   * 语义：**rank 1 = 最高优先级层**。未列出的层（含新增层）排在已知层之后，按名称升序（确定性）。
+   * 注意：这里只定义**偏好顺序**，不定义权重；权重问题走 rank-space（见下），
+   *       需要调权重时应改分档/序，而不是给分数乘系数（Hindsight #3956）。
+   */
+  const layerRankOf = (name) => {
+    const i = FUSION_LAYER_ORDER_V1.indexOf(name)
+    return i >= 0 ? i : FUSION_LAYER_ORDER_V1.length
+  }
+  const cmpLayer = (a, b) => {
+    const la = layerRankOf(String(a.v))
+    const lb = layerRankOf(String(b.v))
+    if (la !== lb) return la - lb
+    const sa = String(a.v), sb = String(b.v)
+    if (sa !== sb) return sa < sb ? -1 : 1
+    return a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0
+  }
+
   const denseRanks = rankArm('dense')
   const lexRanks = rankArm('lex')
 
+  // ★M2.5b 层次臂（2026-09-18）：可选第四臂。layer 为层次名（'project'/'user'/'log'/
+  // 'reflection'/'whiteboard'）或缺失。与时间臂同一条**退化安全**纪律：
+  //   所有 pair 均缺 layer **或 layer 全相等** → 不构建 layer 秩，行为与三臂版**逐字节一致**
+  //   （fused 不加 0 项、输出对象不含新字段）。
+  // 为什么需要它（实测不一致，2026-09-18）：Tier-0 **注入**侧有层次优先级
+  //   （tier-layer-inject.js:58 TIER_LAYER_ORDER_V1 = ['project','whiteboard','user','reflection','log']
+  //    + tier0-catalog.js:419-455 的 caps/floors），而 **排序**侧对层次完全无感
+  //   ⇒ 结论层（project）与流水层（log）在融合里**平等竞争**，笔记层常被日志挤掉。
+  // rank-space（Hindsight #3956 禁止 score-space 加权）：层次只贡献**秩**，不乘分。
+  const layers = []
+  for (const p of list) { if (typeof p.layer === 'string' && p.layer) layers.push(p.layer) }
+  const hasLayer = layers.length > 0 && layers.some((v) => v !== layers[0])
+  const layerRanks = hasLayer ? rankArm('layer', cmpLayer, true) : null
+
   // 时间臂(P12 后新增,2026-09-09):可选第三臂。temp 为 1(命中时间范围)/0(未命中)/
   // 缺失(无时间臂或非日期来源)。所有 pair 均缺 temp **或 temp 全相等**(全 0/全 1)→
   // 不构建 temp 秩,行为与两臂版逐字节一致(fused 不加 0 项、输出对象不含新字段)——
@@ -84,16 +140,31 @@ export function rankFusionRRFPre(pairs, opts = {}) {
         rankDense: rd === undefined ? null : rd,
         rankLex: rl === undefined ? null : rl,
       }
-      if (!hasTemp) return base
-      const rt = tempRanks.get(p.memoryId)
-      const rrfTemp = rt === undefined ? 0 : 1 / (k + rt / divisor)
-      return {
-        ...base,
-        fused: rrfDense + rrfLex + rrfTemp,
-        rrfTemp,
-        tempRaw: typeof p.temp === 'number' && Number.isFinite(p.temp) ? p.temp : null,
-        rankTemp: rt === undefined ? null : rt,
+      // 时间臂与层次臂**互不依赖**：各自独立判 has*，可单独生效、可同时生效。
+      let out = base
+      if (hasTemp) {
+        const rt = tempRanks.get(p.memoryId)
+        const rrfTemp = rt === undefined ? 0 : 1 / (k + rt / divisor)
+        out = {
+          ...out,
+          fused: out.fused + rrfTemp,
+          rrfTemp,
+          tempRaw: typeof p.temp === 'number' && Number.isFinite(p.temp) ? p.temp : null,
+          rankTemp: rt === undefined ? null : rt,
+        }
+      }
+      if (hasLayer) {
+        const rlay = layerRanks.get(p.memoryId)
+        const rrfLayer = rlay === undefined ? 0 : 1 / (k + rlay / divisor)
+        out = {
+          ...out,
+          fused: out.fused + rrfLayer,
+          rrfLayer,
+          layerRaw: typeof p.layer === 'string' && p.layer ? p.layer : null,
+          rankLayer: rlay === undefined ? null : rlay,
+        }
       }
+      return out
     })
     .sort((x, y) => (y.fused !== x.fused ? y.fused - x.fused : (x.memoryId < y.memoryId ? -1 : x.memoryId > y.memoryId ? 1 : 0)))
 }