@a9i5k4/dsh-auto-memory 3.0.1 → 3.1.1

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,6 +136,157 @@ 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' }
@@ -106,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 等):结构化失败,不计崩溃重启
@@ -120,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 }
@@ -133,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')
   }
 
@@ -208,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++
@@ -250,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
@@ -262,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)
@@ -271,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) {
@@ -309,6 +569,10 @@ export function createPythonSidecarClientPre(opts = {}) {
     //   旧代残尾会污染新 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
   }
 
@@ -322,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)),
     }
   }
@@ -330,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
@@ -348,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-stats.js

@@ -0,0 +1,242 @@
+/**
+ * 召回统计（recall statistics）—— 只**记录**、不参与排序。
+ *
+ * **为什么只记录**（用户 2026-09-22 拍板的分步走）：
+ *   加权是**会自我强化**的机制（召回越多 → 权重越高 → 越容易被召回）。在埋点口径未被真实数据
+ *   检验之前就加权，会把口径错误放大成系统性偏差。所以本模块**只累积计数并落盘**，
+ *   `recall()` 的排序与返回**逐字节不变**（守卫断言：本模块的调用不改任何排序输入）。
+ *
+ * ★★ 三条通路**分账**，不混为一谈（用户 2026-09-22 明确要求）：
+ *   同一个「召回」在三条通路里的含义完全不同，合成一个数会误导判断：
+ *   | channel  | 含义             | 语义                 | 用来判断什么           |
+ *   |----------|------------------|----------------------|------------------------|
+ *   | `model`  | 模型主动检索     | 「我明确想找」= 高信号 | 什么内容真的有用、被需要 |
+ *   | `inject` | 每轮自动注入     | 「系统一直塞给我」= 成本 | 注入预算花在哪、哪段最费 |
+ *   | `shadow` | 主动唤起（影子） | 「系统觉得该唤起」= 系统判断质量 | 唤起准不准、命中率如何 |
+ *   ⇒ 若把 inject 与 model 合并，会把「模型懒得检索」误读成「这条不重要」，
+ *     而这个误读会被写进加权公式，越滚越偏。故**必须分开存、分开看**。
+ *
+ * 存储：`~/.dsh/memory/recall-stats.json`（单文件、原子写 tmp→rename、有上限裁剪）。
+ * 设计约束：零依赖（只用 node: 内置）＋ fail-soft（统计坏了绝不影响召回本身）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs'
+import path from 'node:path'
+
+export const RECALL_STATS_VERSION_PRE = 'recall_stats_v1'
+
+/** 三条通路的稳定 id（写盘/前端都按它索引，禁止改拼写）。 */
+export const RECALL_CHANNELS_PRE = ['model', 'inject', 'shadow']
+
+/** 单条记忆的计数上限（超出按 count 升序淘汰最冷门的，防止文件无限增长）。 */
+const MAX_ENTRIES = 2000
+/** 保留天数（按天分布只留最近 N 天）。 */
+const MAX_DAYS = 90
+
+/**
+ * @param {{file: () => string, now?: () => number}} opts
+ *   `file()` 每次调用都重新解析路径（DSH_HOME 可能变），必须是函数而非字符串。
+ */
+export function createRecallStatsPre(opts = {}) {
+  const nowFn = typeof opts.now === 'function' ? opts.now : () => Date.now()
+  const fileOf = typeof opts.file === 'function' ? opts.file : () => ''
+  let state = null
+  let dirty = false
+
+  const dayOf = (ms) => {
+    const d = new Date(ms)
+    const p = (n) => String(n).padStart(2, '0')
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`
+  }
+  /** 一条通路的空白账本。三条各自独立，互不汇总（汇总只发生在 snapshot 的展示层）。 */
+  const emptyChannel = () => ({
+    events: 0,        // 这条通路发生了多少次（检索次数 / 注入轮数 / 唤起次数）
+    hits: 0,          // 命中条目总数（inject 通道为「注入的条目数」）
+    zeroHit: 0,       // 零命中次数（model 通道专有语义；其它通道记为 0）
+    ids: {},          // id → { count, first, last, layer, score, reason }
+    byLayer: {},      // layer → count
+    byDay: {},        // yyyy-mm-dd → count
+    lastAt: 0,
+  })
+  const empty = () => ({
+    version: RECALL_STATS_VERSION_PRE,
+    since: nowFn(),
+    channels: { model: emptyChannel(), inject: emptyChannel(), shadow: emptyChannel() },
+  })
+
+  /** 兼容旧结构（v1 早期是扁平 queries/hits/byLayer…）→ 迁到 channels.model，不丢数据。 */
+  function migrate(d) {
+    if (d && d.channels && typeof d.channels === 'object') {
+      const base = empty()
+      for (const ch of RECALL_CHANNELS_PRE) {
+        base.channels[ch] = Object.assign(emptyChannel(), (d.channels && d.channels[ch]) || {})
+      }
+      base.since = d.since || base.since
+      return base
+    }
+    const base = empty()
+    const m = base.channels.model
+    m.events = Number(d.queries) || 0
+    m.zeroHit = Number(d.zeroHit) || 0
+    m.ids = (d.hits && typeof d.hits === 'object') ? d.hits : {}
+    m.byLayer = (d.byLayer && typeof d.byLayer === 'object') ? d.byLayer : {}
+    m.byDay = (d.byDay && typeof d.byDay === 'object') ? d.byDay : {}
+    m.hits = Object.keys(m.ids).reduce((n, k) => n + ((m.ids[k] && m.ids[k].count) || 0), 0)
+    m.lastAt = Number(d.lastQueryAt) || 0
+    base.since = d.since || base.since
+    return base
+  }
+
+  function load() {
+    if (state) return state
+    state = empty()
+    try {
+      const f = fileOf()
+      if (f && existsSync(f)) {
+        const d = JSON.parse(readFileSync(f, 'utf8'))
+        if (d && typeof d === 'object' && d.version === RECALL_STATS_VERSION_PRE) {
+          state = migrate(d)
+        }
+      }
+    } catch (_) { state = empty() } // 坏文件不阻塞：从零开始，下一轮覆盖写回
+    return state
+  }
+
+  function save() {
+    if (!dirty) return false
+    try {
+      const f = fileOf()
+      if (!f) return false
+      mkdirSync(path.dirname(f), { recursive: true })
+      const tmp = f + '.tmp'
+      writeFileSync(tmp, JSON.stringify(state), 'utf8')
+      renameSync(tmp, f) // 同目录原子替换
+      dirty = false
+      return true
+    } catch (_) {
+      try { if (fileOf()) rmSync(fileOf() + '.tmp', { force: true }) } catch (_) {}
+      return false
+    }
+  }
+
+  /** 裁剪：**每通道**条目数上限 + 天数上限。按 count 升序淘汰最冷门的。 */
+  function prune() {
+    for (const ch of RECALL_CHANNELS_PRE) {
+      const c = state.channels[ch]
+      if (!c) continue
+      const ids = Object.keys(c.ids)
+      if (ids.length > MAX_ENTRIES) {
+        ids.sort((a, b) => (c.ids[a].count || 0) - (c.ids[b].count || 0))
+        for (const id of ids.slice(0, ids.length - MAX_ENTRIES)) delete c.ids[id]
+      }
+      const days = Object.keys(c.byDay)
+      if (days.length > MAX_DAYS) {
+        days.sort()
+        for (const d of days.slice(0, days.length - MAX_DAYS)) delete c.byDay[d]
+      }
+    }
+  }
+
+  /**
+   * 记一次事件。**只读入参、绝不修改** —— 调用方传的 hits/顺序不因本调用而变。
+   *
+   * ★★ channel 必须显式给：`model`（模型主动检索）/ `inject`（每轮自动注入）/ `shadow`（主动唤起）。
+   *   缺省回落到 `model` 只是为了兼容旧调用点；**新调用点一律显式传**。
+   *
+   * @param {Array<{id:string, layer?:string, score?:number, reason?:string}>} hits
+   * @param {{channel?:'model'|'inject'|'shadow', zero?:boolean, label?:string, chars?:number}} [meta]
+   */
+  function observe(hits, meta = {}) {
+    try {
+      const s = load()
+      const t = nowFn()
+      const ch = RECALL_CHANNELS_PRE.indexOf(meta.channel) >= 0 ? meta.channel : 'model'
+      const c = s.channels[ch]
+      c.events += 1
+      c.lastAt = t
+      const list = Array.isArray(hits) ? hits : []
+      // 零命中：对 model 通道是「检索了但没东西」（重要信号）；其它通道同样计数，语义由展示层解释
+      if (!list.length) c.zeroHit += 1
+      c.hits += list.length
+      const d = dayOf(t)
+      for (const h of list) {
+        const id = h && h.id ? String(h.id) : ''
+        if (!id) continue
+        const cur = c.ids[id] || { count: 0, first: t, last: t, layer: '', score: 0, reason: '' }
+        cur.count += 1
+        cur.last = t
+        if (h.layer) cur.layer = String(h.layer)
+        if (typeof h.score === 'number' && isFinite(h.score)) cur.score = h.score
+        // label / chars：注入侧用来回答「哪一段最占预算」（无 id 的段落用它记账）
+        if (h.__label) cur.reason = String(h.__label)
+        if (typeof h.__chars === 'number' && isFinite(h.__chars)) cur.score = h.__chars
+        if (h.reason) cur.reason = String(h.reason)
+        c.ids[id] = cur
+        const lyr = String(h.layer || 'unknown')
+        c.byLayer[lyr] = (c.byLayer[lyr] || 0) + 1
+        c.byDay[d] = (c.byDay[d] || 0) + 1
+      }
+      prune()
+      dirty = true
+      return true
+    } catch (_) { return false } // fail-soft：统计绝不影响召回
+  }
+
+  /** 把一条通路的账本转成只读视图（已排序，直接可画图）。 */
+  function viewOf(c) {
+    const items = Object.keys(c.ids).map((id) => Object.assign({ id }, c.ids[id]))
+    const top = items.slice().sort((a, b) => b.count - a.count || (b.last || 0) - (a.last || 0))
+    const byLayer = Object.keys(c.byLayer).map((k) => ({ key: k, count: c.byLayer[k] }))
+      .sort((a, b) => b.count - a.count)
+    const byDay = Object.keys(c.byDay).sort().map((k) => ({ day: k, count: c.byDay[k] }))
+    return {
+      events: c.events,
+      hits: c.hits,
+      zeroHit: c.zeroHit,
+      lastAt: c.lastAt,
+      distinct: items.length,
+      top: top.slice(0, 200),
+      byLayer,
+      byDay,
+      warm: top.filter((it) => it.count <= 1).length, // 只出现过一次的（"冷门"候选）
+    }
+  }
+
+  /** 面板/路由用的只读视图。**按通道分组返回**，不做跨通道汇总（汇总口径会误导）。 */
+  function snapshot() {
+    const s = load()
+    const channels = {}
+    for (const ch of RECALL_CHANNELS_PRE) channels[ch] = viewOf(s.channels[ch])
+    return {
+      version: RECALL_STATS_VERSION_PRE,
+      since: s.since,
+      channelIds: RECALL_CHANNELS_PRE.slice(),
+      channels,
+    }
+  }
+
+  /** 复位（面板按钮 / 测试）。 */
+  function reset() {
+    state = empty()
+    dirty = true
+    return save()
+  }
+
+  /**
+   * 注入侧的段级记账（没有条目 id 的段落也能记）。
+   * 用途：回答「哪一段最占注入预算」—— 段名当 id，字符数当 score。
+   * @param {Array<{name:string, chars:number, layer?:string}>} segs
+   */
+  function observeInjection(segs) {
+    const list = (Array.isArray(segs) ? segs : [])
+      .filter((s) => s && s.name)
+      .map((s) => ({
+        id: 'seg:' + String(s.name),
+        layer: s.layer || 'section',
+        score: Number(s.chars) || 0,
+        __label: String(s.name) + ' · ' + (Number(s.chars) || 0) + ' 字符',
+      }))
+    return observe(list, { channel: 'inject' })
+  }
+
+  return { observe, observeInjection, snapshot, reset, save, _load: load, _state: () => state }
+}