@a9i5k4/dsh-auto-memory 3.0.1 → 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,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@a9i5k4/dsh-auto-memory",
   "description": "Proactive associative memory for DSH: zero-prompt recall injected before the model speaks, three-layer auto-consolidation, skill crystallization, and Astra-style context management - handoff ledgers, PLAN whiteboard, water-level sensing. Local-first, model-agnostic, zero deps. 主动联想记忆+Astra 式上下文管理:自动唤回/自动沉淀/技能固化/交接账本与白板跨窗口续命/水位感知。",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -15,7 +15,11 @@
     "docs",
     "cordis.patch.yml",
     "!python/bench",
-    "!python/__pycache__"
+    "!python/__pycache__",
+    "!docs/internal",
+    "!docs/**/*.bak",
+    "!docs/**/*.bak-*",
+    "!**/*.mjs.bak-*"
   ],
   "dsh": {
     "bundle": {

package/docs/internal/ACCEPT-35-LIVE.md

@@ -1,143 +0,0 @@
-# #35 真机验收方案（停旧回合 → 仪式 → 真判据 → 新窗口）
-
-> 目标：把 #35 的修复从**夹具级**（`smoke-test-autocont-host-pre.mjs` 95 断言）升级为**真机级**。
-> 本文件给**新会话**执行；执行者不需要读原对话。改配置前先备份（用户级硬规则）。
-
-## 0. 为什么必须换一个会话做
-
-- 验收的**核心那一档**要求在「回合正在运行时点同意」——那会**终止当前回合**。
-  拿重要对话当靶子会打断它，所以：**另开一个新会话当"旧会话"被接续**，本对话不受影响。
-- 新会话要够长、有实质内容（交接材料才有东西可带）；空会话测不出材料质量。
-
-## 1. 前置条件（**2026-09-14 解耦后已更新：只需开一个开关**）
-
-> 历史注记：解耦前 `handoffEnabled=false` 会让 `checkWaterLevel` 提前返回 → `waterLevelModelKnown` 不写 → fail-closed 闸永不 arm，所以当时**必须同时开两个开关**。那处耦合已切除（`lib/index.js` 的 `checkWaterLevel` 早退、`armAutoContinue` 早退、`autoContinueState.enabled` 二次与运算、`buildContinueCarry` 的 `handoff disabled` 早退，共 4 处）。
-
-这台机器的现行配置（`~/.dsh/dsh-auto-memory-pre.json`）：
-
-| 键 | 现值 | 现在的要求 |
-|---|---|---|
-| `autoContinueEnabled` | **false** | **必须临时改 true**——它是接续的唯一资格开关 |
-| `handoffEnabled` | false | **可保持 false**，此时走「最小转写载体」；也可改 true 走完整两层载体（见步骤 1 的 A/B 跑法） |
-| `autoContinueThreshold` | 0.75 | 正常会话很难自然达阈值，验收要临时降 |
-
-**结论：只开 `autoContinueEnabled` 即可跑验收。** 而且**建议第一轮就保持白板关闭**——那条路径是这次解耦才第一次可用的（此前直接 hard-fail），顺带把解耦也验了。
-
-## 2. 步骤
-
-### 步骤 0 · 备份（必做）
-```pwsh
-Copy-Item "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json" "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json.bak-accept35" -Force
-```
-
-### 步骤 1 · 临时开开关 + 降阈值（**A/B 两轮**）
-
-**A 轮（先跑，白板关闭 —— 验解耦后的最小载体）**：
-```json
-"autoContinueEnabled": true,
-"autoContinueThreshold": 0.05
-```
-保持 `handoffEnabled: false` 不动。此轮新会话应拿到**转写包 + 近期线程**，且材料里带一句自述「未启用白板/账本」；仪式步骤会被**跳过**（日志 `reason:'handoff-disabled'`），这是**预期**，不是失败。
-
-**B 轮（A 通过后再跑，白板打开 —— 验完整两层载体）**：
-再把 `"handoffEnabled": true` 打开，重跑一次，观察步骤 ②③ 的仪式链路。
-
-> 为什么降的是 `autoContinueThreshold` 而不是 `waterLevelWindowTokens`：改窗口会让**水位测量本身**失真，连带 advisory 与自动账本写入都变形；降阈值只动"什么时候弹卡"。
-> 每轮改完**重启 dsh web**（注入面与开关在启动时读）。**注意冷却**：`autoContinueCooldownMinutes=30`，触发过一次后 30 分钟内不再弹——两轮之间要么等，要么把冷却临时调小。
-
-### 步骤 2 · 造场景
-在**新会话**里正常跑一两轮（有工具调用、有实质产出）。
-- 注意：**首轮 pre-step 拿不到模型信息**（`request/header` 还没写），按 #33 的 fail-closed 设计，首轮的按比例 arm 会被拦，**推迟到该轮 turn-stopping**。所以卡片应在**第一轮结束后**出现，而不是开局。
-- 若 10 分钟不弹卡：先查日志有没有 `auto-continue armed`，没有就回头查开关与 `modelKnown`（见 §4 排查）。
-
-### 步骤 3 · 点「同意接续」并采日志
-两种点法，验证深度不同——**建议先 A 后 B**：
-
-- **A 档（先做，安全）**：**空闲时点**。验通 ①→④ 全链路与节拍；`cancel` 对空转回合是空操作。
-- **B 档（核心，代价已知）**：**让一个回合跑着（多步工具调用/长输出），在运行中点同意**。这才是 issue 原现场，也是唯一能验「回合活跃时不再并行」的做法。**代价：该回合会被终止，未完成的回答落 `interrupted`。**
-
-采集（改完配置重启后）：
-```pwsh
-Get-Content "$env:USERPROFILE\.dsh\dsh-auto-memory-pre-diagnose.log" -Tail 200 |
-  Select-String 'auto-continue|ritual|prev-session|stopped|waited'
-```
-
-## 3. 判据（缺一不算过；第 3 条仅 B 轮适用，A 轮看 3′）
-
-| # | 期望日志 | 含义 |
-|---|---|---|
-| 1 | `auto-continue armed: … awaitIdle=true …` | 闸放行了（能验到这条本身就说明 #33 的 fail-closed 没误杀） |
-| 2 | **`auto-continue: stopped old turn sid=…`** | **① 新链路真的执行了**；若旧回合在跑，旧窗口应显示被打断 |
-| 3 | **`host refresh ritual: … waited=updated`**（**仅 B 轮／白板开时适用**） | **②③ 因果闭合判据通过**（若显示 `waited=stamp-fallback` → 说明 `sc.inspect` 不可用、退到弱判据，**要当作半通过并单独记**） |
-| 3′ | **A 轮（白板关）替代判据**：日志出现仪式的 `reason:'handoff-disabled'`（仪式按设计被跳过），**且**新会话交接材料里出现「未启用白板/账本」自述、**不含**磁盘上真实存在的 PLAN/账本正文 | 解耦生效：白板关 ≠ 不能接续；且降级是**显式**的，不是静默丢弃 |
-| 4 | `prev-session pack built` → `auto-continue host-executed: … stopped=ok` | ④ 新会话建立；`stopped=ok` 与判据 2 互相印证 |
-
-**反向断言（同样重要）**：
-- 若 ④ 出现但**没有** 2 → 停旧回合没生效（或旧会话无 id，`stopped=no-old-session`），必须记下来；
-- 若旧回合被打断后**新会话没建起来** → 交接失败，比"并行"更糟，立即回滚并报告。
-
-## 4. 排查（卡片不弹时按序查）
-
-1. 开关是否真的生效：`GET /api/dsh-auto-memory-pre/auto-continue-state`（或设置页）看 `enabled`；
-2. 日志有没有 `consolidate skip:` / `auto-continue` 任何一行；
-3. `modelKnown` 是否为真：首轮必为假（设计如此），只在**轮末**才可能 arm；
-4. 冷却：`autoContinueCooldownMinutes=30`，触发过一次后 30 分钟内不再弹——**验收期间只点一次**，要点第二次就先把它调小。
-
-## 5. 回滚（验完必做）
-
-```pwsh
-Copy-Item "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json.bak-accept35" "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json" -Force
-```
-然后重启 dsh web。**除非用户明确要求长期开启**，否则恢复成 `handoffEnabled=false` / `autoContinueEnabled=false` / `autoContinueThreshold=0.75`。
-
-> 待用户裁定（会写进交接账本）：这两个开关**日常要不要开**。若长期关着，则 #35 与 #31 第二半这两笔修复在水位/接续/白板面上**处于不生效状态**——修了但不在线。
-
-## 6. 纪律
-
-- 改配置**必须先备份**（用户级硬规则）；只改目标键，别整篇重写。
-- **不要**按进程名杀进程（曾误杀 harness）；要停就用精确 PID + `taskkill /PID <pid> /T /F`。
-- 不要拿主对话当接续靶子。
-- 验收结论无论通过与否都要落一笔到当日日志；失败要附原始日志片段，不要只写"没通过"。
-
-## 7. 真机验收结果（2026-09-14 17:37–17:41，Run 1）
-
-> 现场：旧会话 `session-d2c13583`（128 msgs）→ 新会话 `session-b8f093e4`。**在飞配置为 `handoffEnabled=true`**（非本文档 §2 设想的 A 轮），故本次实为 **B 轮**（完整两层载体）；**A 轮（白板关）仍未验**。
-> 验收人操作：用户在新窗口点「同意接续」（`decideAutoContinue('agree')`）。
-
-### 判据结果
-
-| # | 结果 | 证据 |
-|---|---|---|
-| 1 | **PASS** | `09:36:52.739Z auto-continue armed: sid=session-d2c13583… ratio=0.07 awaitIdle=true` |
-| 2 | **PASS** | `09:37:37.776Z auto-continue: stopped old turn sid=session-d2c13583…`；旧会话 `turn/end reason.kind=aborted/user` |
-| 3 | **FAIL（原因已查清，非逻辑缺陷）** | `09:39:08.082Z host refresh ritual: timeout, continuing with current material` → `lastOk.refreshRitual='timeout'` |
-| 4 | **PASS** | `09:39:08.106Z prev-session pack built … contSeq=22` → `09:39:08.247Z auto-continue host-executed: new session session-b8f093e4… ritual=timeout stopped=ok` |
-
-**反向断言**：④ 出现且 ② 同时出现 → 停旧回合生效；新会话成功建立（侧栏标题 `接续 #22 · dsh-auto-memory`，工作区/模型/权限 `deepseek-v4.1-flash` + `danger-full-access` 均继承）→ 无"比并行更糟"的交接失败。
-
-### 判据 3 超时的根因（已用旧会话原始事件流取证）
-
-不是判据写错，是**上游 API 故障把仪式推后到轮询窗之外**：
-
-1. `09:37:37.778Z` 仪式以 `mode:'queue'` 投给旧会话，**立刻**落为 `seq=244 user/message`，`turn=3` 同步启动 → 投递链路本身正常。
-2. `turn=3` 全窗没有一次成功的 assistant 产出：`llm/retry` 连续 5 次（`09:37:45`→`09:38:38`，61s），
-   `09:38:38.450Z turn/end reason.kind=error`，错误为 **`502: {"message":"上游拒绝请求","type":"upstream_bad_request"}`**。
-3. 90s 轮询窗（`autoContinueRefreshTimeoutSeconds`）到点 → 报 `timeout`，宿主按 fail-soft 继续接续。
-4. **仪式随后真的执行了**：用户后续「继续」推动 `turn=6`，`09:41:01.529Z`（seq 291–295）模型连调两次
-   `memory_note_pre`（`kind=plan` + `kind=handoff`）→ `PLAN.md` 与 `handoff-20260914-174101.md` 的 mtime 正是 `17:41:01`。
-
-结论：**因果闭合判据的实质成立**（事件数增长且出现 seq>239 的 `assistant/message` + `tool/call`），只是发生在 90s 窗之后（+114s）。**记为半通过**，按本文档 §3 的口径单独记录；若要让它真通过，应提高 `autoContinueRefreshTimeoutSeconds`（当前上限 600）。
-
-### 本轮新发现的真实风险：新会话会被立刻再次 arm（链式接续）
-
-- `09:42:49.340Z auto-continue armed: sid=session-b8f093e4…`（**即刚建出来的新会话**）→ 若无人干预，约 35s 后会再次掐掉新会话并再建一个。
-- 机制：`markContinuedSession(oldSid, newId)` 只给**旧**会话上闩（`isContinuedSession` 检查的是旧 sid）；新会话是全新身份，不受闩保护。而新会话首题就是超大交接包，`ratio` 开局即 ≈0.053。
-- 本次是阈值降到 `0.05` 的**验收态放大**了它；生产阈值 `0.75` 下新会话开局不可能越线，故**当前不判定为缺陷**，但值得在 3.1 决策：新会话是否也应有一段"免接续蜜月期"。
-- **已处置**：`POST /auto-continue-decide {action:'reject'}` 已拆引信（`rejectedEdgeAt=1789378969340`），armed 清空。
-
-### 收尾状态
-
-- 配置已按 §5 回滚：`autoContinueEnabled=false` / `autoContinueThreshold=0.75` / `autoContinueCooldownMinutes=30`（`handoffEnabled` 保持 `true`，与备份一致）。sha `3DEE4041F3E9`。
-- 回滚已**热生效**（`GET /api/dsh-auto-memory-pre/config` 内部会 `loadConfig()` 覆盖内存态；无需重启即生效，实测 `enabled:false`）——这与本文档 §2"每轮改完重启 dsh web"的旧说法不同，**热重载可用**。
-- 验收态快照留存：`~/.dsh/dsh-auto-memory-pre.json.bak-accept35-run1-evidence`。
-- **未验**：A 轮（`handoffEnabled=false`，判据 3′）、B 档"回合运行中点同意"（本次点同意时旧回合已自行 abort，`cancel` 对空转回合是空操作）。