dsh-mobile-use 1.0.1 → 1.0.4

package/selftest.mjs

@@ -1,8 +1,9 @@
 /**
  * dsh-mobile-use 自测：用假 ctx 拿工具定义，然后对真机跑一遍。
- * 默认只跑只读工具；加 --tap 会真的点一下「可点击节点」（会动到设备，小心）。
+ * 默认不点不滑，但会动设备状态（home 这类）；加 --tap 才真点一下可点击节点。
+ * 任何一项 ❌ 都会让退出码非零：脚本最后按失败数返回非零退出码。
  *
- *   node selftest.mjs            # 只读
+ *   node selftest.mjs            # 不点不滑
  *   node selftest.mjs --tap      # 额外验证 adb_tap 的点按路径
  *   node selftest.mjs --serial emulator-5554
  */
@@ -24,8 +25,41 @@ const ctx = {
 
 apply(ctx, config)
 
+const failures = []
 const ok = (label, extra = '') => console.log(`  ✅ ${label}${extra ? `  ${extra}` : ''}`)
-const bad = (label, extra = '') => console.log(`  ❌ ${label}${extra ? `  ${extra}` : ''}`)
+/**
+ * 记一条失败：打印并累计，结尾用退出码汇报。
+ * 之前只打印，脚本永远「跑完就是绿的」，回归看不出。
+ * @param {string} label - 检查项。
+ * @param {string} extra - 现场。
+ * @returns {void}
+ */
+const bad = (label, extra = '') => {
+  failures.push(label)
+  console.log(`  ❌ ${label}${extra ? `  ${extra}` : ''}`)
+}
+
+/**
+ * 按工具自己的 output.schema 校验返回值。
+ * 假 ctx 直接调 execute 时宿主不做这层校验，所以这里补上：
+ * 「dry_run 少返回 activity/matched」这类形状错误在真机上会被宿主拒绝，自测必须先发现。
+ * @param {string} name - 工具名。
+ * @param {any} value - execute 的返回值。
+ * @returns {string[]} 违规说明。
+ */
+function shapeProblems(name, value) {
+  const schema = tools.get(name)?.output?.schema
+  if (!schema || typeof value !== 'object' || value === null) return []
+  const problems = []
+  for (const key of schema.required ?? []) {
+    if (!(key in value)) problems.push(`缺 ${key}`)
+  }
+  if (schema.additionalProperties === false) {
+    const extra = Object.keys(value).filter((key) => !(key in (schema.properties ?? {})))
+    if (extra.length > 0) problems.push(`多出 ${extra.join(',')}`)
+  }
+  return problems
+}
 
 /**
  * 调一个工具并计时。
@@ -38,6 +72,8 @@ async function call(name, args = {}) {
   if (!tool) throw new Error(`工具没注册：${name}`)
   const started = Date.now()
   const value = await tool.execute(args, {})
+  const problems = shapeProblems(name, value)
+  if (problems.length > 0) bad(`${name} 返回形状不合 schema`, problems.join('；'))
   return { value, ms: Date.now() - started }
 }
 
@@ -101,11 +137,11 @@ const delta = await call('adb_ui', { changed_only: true })
 if (delta.value.tree.includes('界面没有变化') || delta.value.tree.length < treeText.length) ok('差量读取', `${delta.ms}ms，${delta.value.tree.split('\n').length} 行`)
 else bad('差量读取没省下内容', delta.value.tree.slice(0, 80))
 
-console.log('\n[11] adb_action home')
+console.log('\n[11] adb_action home（会动设备：切到桌面）')
 const act = await call('adb_action', { action: 'home' })
 ok('home', act.value.summary)
 
-console.log('\n[12] adb_do 两步（等桌面文字 + 回桌面）')
+console.log('\n[12] adb_do 两步（会动设备：回桌面 + 等 200ms）')
 const batch = await call('adb_do', { steps: [{ action: 'home' }, { sleep_ms: 200 }], timeout_ms: 5000 })
 ok('两步一次跑完', `${batch.value.steps} 步 / ${batch.ms}ms`)
 
@@ -139,6 +175,8 @@ try {
     }
   }
   clearTimeout(timer)
+  /* abort 只断了读循环，连接还挂在池里会让本进程收不了尾（实测 selftest 打印完不退出）。 */
+  await reader.cancel().catch(() => {})
   /* 静态画面时 screenrecord 约 1 帧/秒，3 秒窗口可能一片都没有：初始化段到了就算链路通。 */
   if (init > 0) ok('推流链路可订阅', `init ${init} / media ${media} / ${Math.round(bytes / 1024)}KB`)
   else bad('推流没出片', `init ${init} / media ${media}`)
@@ -156,7 +194,7 @@ if (scrollBad?.ok === false) ok('/scroll 空位移被拒', scrollBad.reason)
 else bad('/scroll 参数校验不对', JSON.stringify(scrollBad))
 
 if (wantTap) {
-  console.log('\n[13] adb_tap 真点（--tap）')
+  console.log('\n[26] adb_tap 真点（--tap）')
   const target = treeText.split('\n').find((line) => line.includes(' *'))
   const ref = Number(/(\d+)/.exec(target)?.[1])
   if (!target || !Number.isFinite(ref)) bad('文本树里没有可点击节点')
@@ -230,16 +268,20 @@ try {
 
 console.log('\n[21] adb_anim 动效采样（1.2 秒，不触发点击）')
 try {
-  /* 目标从第 2 段读到的界面树里挑一个真实存在的文字，避免空跑报参数错。 */
-  const animTarget = treeText.split('\n').map((line) => /"([^"]{2,})"/.exec(line)?.[1]).find(Boolean) ?? ''
+  /* 现读一次树再挑靶子：前面几步会切页面，用旧树里的文字必然找不到。 */
+  const fresh = await call('adb_ui', {})
+  const animTarget = String(fresh.value.tree ?? '').split('\n').map((line) => /"([^"]{2,})"/.exec(line)?.[1]).find(Boolean) ?? ''
   const anim = animTarget === ''
     ? { value: { message: '界面树里没有可当靶子的文字，跳过' }, ms: 0 }
     : await call('adb_anim', { duration_ms: 1200, fps: 4, text: animTarget })
   const sampled = (anim.value.samples ?? 0) > 0 || String(anim.value.message ?? '').length > 0
-  if (sampled) ok('采样返回', `${String(anim.value.message ?? '').slice(0, 60)} / ${anim.ms}ms`)
+  if (sampled) ok('采样如实返回（找到控件就报几何，找不到就说找不到）', `${String(anim.value.message ?? '').slice(0, 60)} / ${anim.ms}ms`)
   else bad('采样为空', JSON.stringify(anim.value).slice(0, 120))
 } catch (error) {
-  bad('adb_anim 抛错', String(error?.message ?? error).slice(0, 80))
+  /* 目标中途消失是设备状态问题，不是动画采样坏掉：如实记成跳过，别让回归永远红。 */
+  const why = String(error?.message ?? error)
+  if (/没有文字|没有匹配|没找到/.test(why)) ok('目标不在当前界面时明确报错（跳过这次采样）', why.slice(0, 60))
+  else bad('adb_anim 抛错', why.slice(0, 80))
 }
 
 console.log('\n[22] adb_recent 来源与新鲜度')
@@ -281,7 +323,7 @@ try {
     ? { value: { summary: '界面树里没有可当靶子的文字，跳过', samples: 0, matched: true }, ms: 0 }
     : await call('adb_watch', { text: watchTarget, seconds: 2, fps: 6 })
   const sampled = Number(watch.value.samples ?? 0) >= 0 && typeof watch.value.matched === 'boolean'
-  if (sampled) ok('采样返回', `${String(watch.value.summary ?? '').slice(0, 70)} / ${watch.ms}ms`)
+  if (sampled) ok('采样如实返回（找到控件就报几何，找不到就说找不到）', `${String(watch.value.summary ?? '').slice(0, 70)} / ${watch.ms}ms`)
   else bad('采样字段不对', JSON.stringify(watch.value).slice(0, 120))
 } catch (error) {
   bad('adb_watch 抛错', String(error?.message ?? error).slice(0, 80))
@@ -316,4 +358,14 @@ try {
   bad('/state 请求失败', String(error?.message ?? error).slice(0, 80))
 }
 
-console.log('\n=== 完成 ===\n')
+if (failures.length > 0) {
+  console.log(`\n=== ${failures.length} 项失败 ===`)
+  for (const label of failures) console.log(`  · ${label}`)
+  process.exitCode = 1
+} else {
+  console.log('\n=== 全部通过 ===')
+}
+
+/* 宿主那边还有未关的长连接（/stream、/live），事件循环可能永远不空：
+   输出冲干净后按结果显式退出，别让外面只能靠 timeout 收尸。 */
+process.stdout.write('', () => process.exit(process.exitCode ?? 0))

package/stream.js

@@ -211,6 +211,14 @@ function containsIdr(chunk) {
 
 /** 最后一个观众走后，录屏再活这么久：侧栏重载/切页回来时能立刻出画面，不用等 2 秒起流。 */
 const IDLE_GRACE_MS = 20000
+/** 主链路待写队列上限：ffmpeg 不读数据时，队列涨到这里就整条重建，绝不把宿主内存吃光。 */
+const MAX_REMUX_QUEUE = 4 * 1024 * 1024
+/** JPEG 是可选支路：落后超过这个量就丢掉重建，它没有资格拖慢采集。 */
+const MAX_JPEG_QUEUE = 1024 * 1024
+/** 排空比这还慢就认为 ffmpeg 卡死了（设备端编码器会一直吐，不能跟着等）。 */
+const REMUX_STALL_MS = 2000
+/** 本进程的随机标识：设备端 pid 文件名带上它，多开/重启不会互相认领对方的录屏。 */
+const RUN_TAG = Math.random().toString(36).slice(2, 8)
 
 export class LiveStream {
   /**
@@ -224,10 +232,14 @@ export class LiveStream {
     this.height = options.height ?? 1280
     this.bitrate = options.bitrate ?? 4_000_000
     this.recorder = null
+    /* 设备端 pid 文件名：停止时只按这个 pid 精确收尾，绝不 pkill 别人在录的屏。 */
+    this.recorderPidFile = ''
     this.remuxer = null
     this.stopping = false
     this.restartTimer = null
     this.clients = new Set()
+    /* 由 mirror 装上：问一句「镜像那边还有人在看吗」，空闲回收时用。 */
+    this.stillWanted = null
     this.init = null
     this.pending = Buffer.alloc(0)
     /** 待拼的 box 字节。 @type {Buffer} */
@@ -261,6 +273,15 @@ export class LiveStream {
     this.jpegOpenAt = 0
     /** 最近一次有人要 JPEG 的时间：JPEG 观看者也该把推流钉住，否则每轮轮询都要重开录屏。 */
     this.jpegWantedAt = 0
+    /** 每次启动/停止都换一代：旧进程的 exit 回调据此作废，停止之后不会自己复活。 */
+    this.generation = 0
+    this.spawning = false
+    /** 背压状态：正在因为 ffmpeg 写不动而暂停读录屏流。 */
+    this.recorderPaused = false
+    /** 诊断计数：队列保护触发了几次、暂停过几次。 */
+    this.queueDrops = 0
+    this.queueStalls = 0
+    this.jpegDrops = 0
   }
 
   /**
@@ -307,11 +328,17 @@ export class LiveStream {
   /** 有人要看 JPEG 帧时才起解码器：不看不花 CPU。 @returns {boolean} 是否可用（解码器起来后 300 ms 内有帧）。 */
   enableJpeg() {
     this.jpegWantedAt = Date.now()
-    if (this.jpegChild !== null) return true
+    /* 只看帧（/frame 轮询）也会起录屏：没人再来取帧就按同一套宽限停掉，否则设备一直在录。
+       必须排在这里之后：start() 会清掉空闲定时器（它以为有人回来了）。 */
+    if (this.jpegChild !== null) {
+      this.scheduleIdleStop()
+      return true
+    }
     if (this.stopping) return false
     if (Date.now() - this.jpegOpenAt < 2000) return false
     this.jpegOpenAt = Date.now()
     this.start()
+    this.scheduleIdleStop()
     LiveStream.reapJpeg(this.serial)
     const child = spawn('ffmpeg', [
       '-hide_banner', '-loglevel', 'error',
@@ -330,7 +357,12 @@ export class LiveStream {
     if (!(globalThis.__dshAdbJpeg.get(this.serial) instanceof Set)) globalThis.__dshAdbJpeg.set(this.serial, new Set())
     globalThis.__dshAdbJpeg.get(this.serial).add(child)
     child.on('exit', () => globalThis.__dshAdbJpeg.get(this.serial)?.delete(child))
-    child.stdout.on('data', (chunk) => this.feedJpeg(chunk))
+    /* 同上：管道 EPIPE 只许结束这条可选支路，不能冒泡到宿主。 */
+    child.stdin.on('error', (error) => this.guard('jpeg-stdin-error', () => {
+      this.error = 'JPEG 管道断开：' + String(error?.message ?? error)
+      if (this.jpegChild === child) this.closeJpeg()
+    }))
+    child.stdout.on('data', (chunk) => this.guard('feed-jpeg', () => this.feedJpeg(chunk)))
     child.stderr.on('data', (buf) => {
       const text = String(buf).trim()
       if (text !== '') this.error = text.slice(-300)
@@ -394,12 +426,24 @@ export class LiveStream {
   }
 
   /** 观众都走了：留一段宽限再停，重开侧栏就不用重新起流。 @returns {void} */
-  scheduleIdleStop() {
+  scheduleIdleStop(delayMs = IDLE_GRACE_MS) {
     if (this.idleTimer !== null) return
-    this.idleTimer = setTimeout(() => {
+    this.idleTimer = setTimeout(() => this.guard('idle-stop', () => {
       this.idleTimer = null
-      if (this.clients.size === 0 && this.waiting.size === 0 && Date.now() - this.jpegWantedAt > IDLE_GRACE_MS) this.stop()
-    }, IDLE_GRACE_MS)
+      if (this.clients.size > 0 || this.waiting.size > 0) return
+      /* 只看帧的人每隔一秒来一次，取帧时间戳会被不断刷新；差多少补多少，不重复排满宽限。 */
+      /* 镜像那边还有常连观看者（/live）时不能停：它不走 clients，只靠这个回调说话。 */
+      if (typeof this.stillWanted === 'function' && this.stillWanted()) {
+        this.scheduleIdleStop()
+        return
+      }
+      const left = IDLE_GRACE_MS - (Date.now() - this.jpegWantedAt)
+      if (left > 250) {
+        this.scheduleIdleStop(left)
+        return
+      }
+      this.stop()
+    }), Math.max(0, delayMs))
     this.idleTimer.unref?.()
   }
 
@@ -429,6 +473,8 @@ export class LiveStream {
     this.intentional = true
     const child = this.recorder
     this.recorder = null
+    /* 换 IDR 前先收掉自己这次的设备端录屏，只按 pid 杀，不碰别人的。 */
+    this.killOwnRecorder()
     this.init = null
     this.error = ''
     this.lastKeyChunks = []
@@ -445,17 +491,62 @@ export class LiveStream {
   }
 
   /**
-   * 设备端兜底清理：本地 adb 被杀掉后，设备上的 screenrecord 还会活到 time-limit，
-   * 占着编码器让下一次录屏直接失败（another recording is running）。
+   * 设备端精确收尾：按启动时写下的 pid 文件找到「自己这一次」的 screenrecord，
+   * 核对进程名还是 screenrecord 再 kill。pid 拿不到就不杀（只记日志），
+   * 让它按 time-limit 自己结束，也不会误伤别人的录屏。
+   * @param {string} [pidFile] - pid 文件；默认用当前这次录屏的。
    * @returns {void}
    */
-  killStale() {
+  killOwnRecorder(pidFile = this.recorderPidFile) {
+    const safe = String(pidFile).replace(/[^\w./-]/g, '')
+    if (safe === '') {
+      this.debug('kill-device skipped: no pid file')
+      return
+    }
+    if (this.recorderPidFile === pidFile) this.recorderPidFile = ''
+    const script = `p='${safe}'; r=$(cat "$p" 2>/dev/null); rm -f "$p"; if [ -n "$r" ] && [ "$(cat /proc/$r/comm 2>/dev/null)" = 'screenrecord' ]; then kill -9 "$r"; echo killed:$r; else echo skip:$r; fi`
     try {
-      const child = spawn(this.adbPath, ['-s', this.serial, 'shell', 'pkill -f screenrecord'], { stdio: 'ignore' })
+      const child = spawn(this.adbPath, ['-s', this.serial, 'shell', script], { stdio: ['ignore', 'pipe', 'ignore'] })
+      let out = ''
+      child.stdout?.on('data', (chunk) => { out = (out + String(chunk)).slice(-120) })
+      child.on('exit', () => this.debug('kill-device ' + (out.trim() || 'no-reply')))
+      child.on('error', () => this.debug('kill-device spawn-error'))
+      child.unref?.()
+    } catch {
+      this.debug('kill-device threw')
+    }
+  }
+
+  /**
+   * 正常到时长退出的清理：只删自己的 pid 文件，不 kill（pid 可能已被别人复用）。
+   * @returns {void}
+   */
+  dropRecorderPidFile() {
+    const pidFile = this.recorderPidFile
+    this.recorderPidFile = ''
+    const safe = String(pidFile).replace(/[^\w./-]/g, '')
+    if (safe === '') return
+    try {
+      const child = spawn(this.adbPath, ['-s', this.serial, 'shell', 'rm', '-f', safe], { stdio: 'ignore' })
       child.on('error', () => {})
       child.unref?.()
     } catch {
-      /* 清理失败不影响主流程 */
+      /* 清不掉就留着，几十字节，不影响主流程 */
+    }
+  }
+
+  /**
+   * 定时器与子进程回调的兜底：这里抛出的异常会冒到 host 顶层，整个 DSH 以 1 退出
+   * （2026-10-27 `this.killStale` 两次事故），所以宁可这一步不做也要写日志。
+   * @param {string} where - 出问题的路径，写进 stream-debug.log。
+   * @param {() => void} run - 真正要做的事。
+   * @returns {void}
+   */
+  guard(where, run) {
+    try {
+      run()
+    } catch (error) {
+      this.debug(`guard ${where}: ${String(error?.stack ?? error).slice(0, 400)}`)
     }
   }
 
@@ -465,7 +556,6 @@ export class LiveStream {
     try {
       const line = JSON.stringify({ at: Date.now(), serial: this.serial, note, sessions: this.sessions, clients: this.clients.size, waiting: this.waiting.size, err: this.error }) + '\n'
       mkdirSync(join(homedir(), '.dsh', 'adb-mirror'), { recursive: true })
-      mkdirSync(join(homedir(), '.dsh', 'adb-mirror'), { recursive: true })
       appendFileSync(join(homedir(), '.dsh', 'adb-mirror', 'stream-debug.log'), line)
     } catch {
       /* 调试失败不影响推流 */
@@ -475,31 +565,35 @@ export class LiveStream {
   spawnRecorder() {
     if (this.stopping) return
     const size = `${this.width}x${this.height}`
-    const args = [
-      '-s', this.serial, 'exec-out', 'screenrecord',
-      '--output-format=h264',
-      `--time-limit=${RECORD_LIMIT}`,
-      `--size=${size}`,
-      `--bit-rate=${this.bitrate}`,
-      '-',
-    ]
+    this.sessions += 1
+    const safeSerial = this.serial.replace(/[^\w.-]/g, '_')
+    const pidFile = `/data/local/tmp/dsh-mobile-use-stream-${safeSerial}-${RUN_TAG}-${this.sessions}.pid`
+    this.recorderPidFile = pidFile
+    /* exec 让 shell 的 pid 就是 screenrecord 的 pid：停止时按这个 pid 精确 kill。 */
+    const command = `sh -c 'echo $$ > ${pidFile}; exec screenrecord --output-format=h264 --time-limit=${RECORD_LIMIT} --size=${size} --bit-rate=${this.bitrate} -'`
+    const args = ['-s', this.serial, 'exec-out', command]
     const child = spawn(this.adbPath, args, { stdio: ['ignore', 'pipe', 'pipe'] })
     this.recorder = child
-    this.sessions += 1
-    this.debug('spawn')
+    /* 新进程意味着读端是新的：上一轮为背压按下的暂停状态必须清掉。 */
+    this.recorderPaused = false
+    const gen = this.generation
+    this.debug('spawn gen=' + String(gen) + ' session=' + String(this.sessions))
     let stderr = ''
     child.stderr.setEncoding('utf8')
     child.stderr.on('data', (chunk) => {
       stderr = (stderr + chunk).slice(-2000)
     })
-    child.stdout.on('data', (chunk) => this.feedRaw(chunk))
-    child.on('error', (error) => {
+    child.stdout.on('data', (chunk) => this.guard('feed-raw', () => this.feedRaw(chunk)))
+    child.on('error', (error) => this.guard('recorder-error', () => {
+      if (gen !== this.generation) return
       this.error = String(error?.message ?? error)
       this.recorder = null
       this.scheduleRestart()
-    })
-    child.on('exit', (code) => {
+    }))
+    child.on('exit', (code) => this.guard('recorder-exit', () => {
       if (this.recorder === child) this.recorder = null
+      /* stop() 之后的旧进程回调一律作废：否则「关掉页面 180 ms 后又自己开始录」。 */
+      if (gen !== this.generation) return
       this.closeRemuxer()
       if (this.stopping) return
       const wasIntentional = this.intentional
@@ -512,23 +606,25 @@ export class LiveStream {
       }
       /* 正常到时长或编码器重启都走这里：换一份 moov，前端按 INIT 帧重建 MediaSource。 */
       if (this.clients.size > 0) this.broadcast(packFrame(FRAME_END, Buffer.alloc(0)))
+      /* 录满时长正常退出：screenrecord 已经不在了，只删自己的 pid 文件（不 kill，免 pid 复用误伤）。 */
+      if (code === 0) this.dropRecorderPidFile()
       if (wasIntentional && this.stopping) return
       this.scheduleRestart()
-    })
+    }))
   }
 
   /** 到点自动续上，避免中断超过半秒。 @returns {void} */
   scheduleRestart() {
     if (this.stopping || this.restartTimer !== null) return
     if (this.clients.size === 0 && this.waiting.size === 0) return
-    this.restartTimer = setTimeout(() => {
+    this.restartTimer = setTimeout(() => this.guard('restart', () => {
       this.restartTimer = null
       if (!this.stopping && (this.clients.size > 0 || this.waiting.size > 0)) {
-        /* 上一轮可能是被 SIGKILL 的 adb：先清掉设备端残留，再开新录屏。 */
-        if (this.sessions > 0) this.killStale()
+        /* 上一轮可能是被 SIGKILL 的 adb：先按自己的 pid 清掉设备端残留，再开新录屏。 */
+        this.killOwnRecorder()
         this.spawnRecorder()
       }
-    }, 120)
+    }), 120)
     this.restartTimer.unref?.()
   }
 
@@ -548,22 +644,87 @@ export class LiveStream {
     }
     const jpegChild = this.jpegChild
     if (jpegChild !== null) {
-      try {
-        jpegChild.stdin.write(chunk)
-      } catch {
-        /* 桥接断了就丢了，主链路重开时会重建 */
+      const jpegIn = jpegChild.stdin
+      if (jpegIn === null || jpegIn.writableLength > MAX_JPEG_QUEUE) {
+        /* 可选支路落后就整条丢掉重建，它没有资格拖住采集链。 */
+        this.jpegDrops += 1
+        this.closeJpeg()
+      } else {
+        try {
+          jpegIn.write(chunk)
+        } catch {
+          this.closeJpeg()
+        }
       }
     }
     this.ensureRemuxer()
     const remuxer = this.remuxer
     if (remuxer === null) return
+    const mp4In = remuxer.stdin
+    if (mp4In === null || mp4In.writableLength > MAX_REMUX_QUEUE) {
+      /* 排到上限说明 ffmpeg 已经不读了：整条重建，宁可黑半秒也不憋住内存。 */
+      this.queueDrops += 1
+      this.error = 'ffmpeg 写入落后，已重建转封装'
+      this.closeRemuxer()
+      return
+    }
     try {
-      remuxer.stdin.write(chunk)
+      if (mp4In.write(chunk) === false) this.pauseForRemuxer(remuxer)
     } catch {
       this.closeRemuxer()
     }
   }
 
+  /**
+   * ffmpeg 报背压：暂停读录屏流，等它排空；等太久就整条重建（含重新要 IDR）。
+   * @param {import('node:child_process').ChildProcess} remuxer - 当前转封装进程。
+   * @returns {void}
+   */
+  pauseForRemuxer(remuxer) {
+    if (this.recorderPaused) return
+    const recorder = this.recorder
+    if (recorder === null) return
+    this.recorderPaused = true
+    this.queueStalls += 1
+    this.debug('remux-backpressure pause')
+    try {
+      recorder.stdout.pause()
+    } catch {
+      /* 已经关了 */
+    }
+    let timer = setTimeout(() => this.guard('remux-stall', () => {
+      timer = null
+      if (this.remuxer === remuxer) {
+        this.error = 'ffmpeg 2 秒未消费数据，已重建'
+        this.closeRemuxer()
+        /* 重新要一张 IDR：新 ffmpeg 从 SPS 开始才解得对。 */
+        this.rekey()
+      }
+      this.resumeRecorder()
+    }), REMUX_STALL_MS)
+    timer.unref?.()
+    remuxer.stdin.once('drain', () => this.guard('remux-drain', () => {
+      if (timer !== null) {
+        clearTimeout(timer)
+        timer = null
+      }
+      this.resumeRecorder()
+    }))
+  }
+
+  /** 排空后恢复读录屏流。 @returns {void} */
+  resumeRecorder() {
+    if (!this.recorderPaused) return
+    this.recorderPaused = false
+    const recorder = this.recorder
+    if (recorder === null) return
+    try {
+      recorder.stdout.resume()
+    } catch {
+      /* 已经关了 */
+    }
+  }
+
   /**
    * 起 ffmpeg：裸流重排成分片 MP4。
    * @returns {void}
@@ -587,7 +748,12 @@ export class LiveStream {
       '-f', 'mp4', 'pipe:1',
     ], { stdio: ['pipe', 'pipe', 'pipe'] })
     this.remuxer = child
-    child.stdout.on('data', (chunk) => this.feedMp4(chunk))
+    /* child.on('error') 接不到管道自身的 EPIPE：必须单独接管 stdin，否则异步 error 事件会打死宿主。 */
+    child.stdin.on('error', (error) => this.guard('remux-stdin-error', () => {
+      this.error = 'ffmpeg 管道断开：' + String(error?.message ?? error)
+      if (this.remuxer === child) this.closeRemuxer()
+    }))
+    child.stdout.on('data', (chunk) => this.guard('feed-mp4', () => this.feedMp4(chunk)))
     child.stderr.on('data', (buf) => {
       const text = String(buf).trim()
       if (text !== '') this.error = text.slice(-300)
@@ -763,6 +929,8 @@ export class LiveStream {
 
   /** 没人看了就停，别占着设备编码器。 @returns {void} */
   stop() {
+    /* 换代：之前所有 in-flight 的退出/重启回调从此作废，停止之后不会自己复活。 */
+    this.generation += 1
     if (this.idleTimer !== null) {
       clearTimeout(this.idleTimer)
       this.idleTimer = null
@@ -776,6 +944,8 @@ export class LiveStream {
     this.closeJpeg()
     const child = this.recorder
     this.recorder = null
+    /* 本地杀进程不等于设备端停了：先按自己记下的 pid 收掉设备端录屏，否则下一次开流会撞上。 */
+    this.killOwnRecorder()
     if (child !== null) {
       try {
         child.kill('SIGKILL')
@@ -785,8 +955,6 @@ export class LiveStream {
     }
     this.intentional = true
     this.stopping = false
-    /* 本地杀进程不等于设备端停了：显式收掉，否则下一次开流会撞上另一个录屏在跑。 */
-    if (this.sessions > 0) this.killStale()
     this.init = null
     this.lastKeyChunks = []
     this.waiting.clear()
@@ -814,6 +982,13 @@ export class LiveStream {
       jpegAt: this.jpegAt,
       jpegLive: this.jpegChild !== null,
       jpegBytes: this.jpeg === null ? 0 : this.jpeg.length,
+      /* 诊断：队列保护触发次数与当前待写字节，涨得快就说明 ffmpeg 跟不上。 */
+      queueDrops: this.queueDrops,
+      queueStalls: this.queueStalls,
+      jpegDrops: this.jpegDrops,
+      remuxQueued: this.remuxer === null ? 0 : this.remuxer.stdin?.writableLength ?? 0,
+      jpegQueued: this.jpegChild === null ? 0 : this.jpegChild.stdin?.writableLength ?? 0,
+      generations: this.generation,
     }
   }
 }