@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/daemon/framed.mjs

@@ -15,9 +15,11 @@
  *                  { kind:'frame', meta, preview }         （每接受帧的元数据与预览帧路径）
  *                  { kind:'event', ev }                    （变化/稳定/节点事件）
  *                  { kind:'stream_error', error }
+ *                  { kind:'stream_stopped', reason }       （控制器被销毁→帧流主动停止；
+ *                                                            要看帧就重新 stream_start）
  */
 import { createRequire } from 'node:module'
-import { execFile, spawn } from 'node:child_process'
+import { execFile, spawn, spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { createHash, randomUUID } from 'node:crypto'
 import readline from 'node:readline'
@@ -116,6 +118,21 @@ function pngDecode(buf) {
   }
   return { w, h, ch, data: out }
 }
+/** PNG 声明尺寸（只读 IHDR，不解像素）。
+ *
+ * 为什么要有这个：`--image` 分支的回执只带 `{source}`，调用方拿到图却不知道它多大，
+ * 于是 **roi 空间错了也无从判断**（ctrl 空间 roi 打到 L1 小图上，静默零例）。
+ * 与 pngDecode 的第二层同为「读 IHDR 才拿到 w/h」，但**不做解码**——这里只要尺寸，
+ * 真解码交给 reco 子进程；文件不可读 / 不是 PNG 时返回 null，让子进程去报真正的读取错误。
+ * 名字带 Header 以区别于 image.ts 里那个会完整解码的异步 pngSize。 */
+function pngHeaderSize(buf) {
+  try {
+    if (buf[0] !== 0x89 || buf[1] !== 0x50) return null
+    const len = buf.readUInt32BE(8)
+    if (buf.toString('ascii', 12, 16) !== 'IHDR' || len < 8) return null
+    return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) }
+  } catch (e) { return null }
+}
 /** 归一化为 RGB（丢弃 alpha），返回新 Buffer */
 function toRgb(dec) {
   if (dec.ch === 3) return dec.data
@@ -212,7 +229,10 @@ const KF_QUOTA_DEFAULT = (() => {
   return Number.isFinite(v) && v > 0 ? v : 1024 * 1024 * 1024
 })()
 const S = {
-  ctrl: null, res: null, tasker: null,
+  ctrl: null, tasker: null,
+  /* 最近一次 run / --act 的 Resource：只作释放点（换新时 destroy 上一份、disconnect 时销毁），
+   * 不当"当前资源"共享——那会让下一次命令带着上一轮的 bundle 跑。 */
+  runRes: null,
   session: null,                       // { kind, target, method }
   daemonId: randomUUID(),              // 本 daemon 实例身份（留存记录的 session.daemon）
   connGen: 0,                          // 连接代次：每次 connect 成功 +1（留存记录定位用）
@@ -264,6 +284,58 @@ async function cmdProbe() {
   return out
 }
 
+/**
+ * 截图能力探测（示范轨迹契约 §3）：决定能不能走 A 路（人在我们显示的帧上点）。
+ * 方法：两次 post_screencap 间隔抓帧，比 blockHash 与亮度。
+ *   changed == true                          → 像素在变（遮挡下能变 = 后台可截）
+ *   changed == false 且 mean 正常            → 静止（目标停止渲染？改应用设置，不是截图路径问题）
+ *   mean < 8                                 → 黑图（截图方法不兼容，换一个）
+ *   post_screencap 抛错/空                   → 报错（如实带出）
+ * 探针不知道"此刻是否遮挡"——判据只在遮挡态成立，调用方（CLI）负责提示与如实标注。
+ */
+async function cmdScreencapProbe(args) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备（先 connect）' }
+  const interval = Math.min(20000, Math.max(500, Number(args.intervalMs ?? 3000)))
+  const grab = async () => {
+    try {
+      const j = S.ctrl.post_screencap()
+      await j.wait()
+      const buf = j.get()
+      if (!buf || buf.byteLength < 9) return { ok: false, error: '空截图' }
+      const dec = pngDecode(Buffer.from(buf))
+      const rgb = toRgb(dec)
+      const hash = blockHash(rgb, dec.w, dec.h)
+      /* 黑帧判定用平均亮度：全黑截图的 mean≈0，正常画面几十起步；阈值取 8 有充分余量 */
+      let sum = 0
+      for (let i = 0; i < rgb.length; i++) sum += rgb[i]
+      const mean = Math.round((sum / rgb.length) * 10) / 10
+      return { ok: true, w: dec.w, h: dec.h, hash: hashStr(hash), mean }
+    } catch (e) {
+      return { ok: false, error: String(e && e.message || e) }
+    }
+  }
+  const first = await grab()
+  await sleep(interval)
+  const second = await grab()
+  if (!first.ok || !second.ok) {
+    return { ok: true, intervalMs: interval, first, second, changed: null,
+      verdict: 'error',
+      note: 'post_screencap 报错或返回空——截图方法不兼容或控制器异常，换 win32.screencap 方法重试。' }
+  }
+  const changed = first.hash !== second.hash
+  let verdict = 'changing'
+  let note = '像素在变：若此刻窗口被完全遮挡，即"后台可截"（A 路前提成立）。'
+  if (!changed && second.mean < 8) {
+    verdict = 'black'
+    note = '截图近乎全黑：截图方法不兼容这台设备/这个窗口——换 win32.screencap 方法（FramePool / PrintWindow）重试。'
+  } else if (!changed) {
+    verdict = 'static'
+    note = '像素静止：目标停止渲染（改模拟器/应用设置），或两帧之间画面恰好没动——遮挡下再测一次确认。'
+  }
+  return { ok: true, intervalMs: interval, first, second, changed, verdict, note,
+    occluded: args.occluded === true ? true : null }
+}
+
 async function cmdDeviceList(kind) {
   const m = loadMaa()
   const list = []
@@ -318,9 +390,76 @@ function resolveEnum(table, value, fallback, label, warns) {
   return String(fallback)
 }
 
+/**
+ * LinuxController 的 config JSON 组装（maa-support-extension buildControllerRuntime /
+ * MXU build_linux_controller_config 同款规则，纯函数、与宿主平台无关，供单测直测）：
+ *   1) args.target/config 是 JSON 串 → 原样用（字段全集归用户管，逃逸口）；
+ *   2) 否则按 linuxDecl（interface.json linux{}）+ args.linux（用户字段）组 JSON：
+ *      方法名→数值枚举、缺省 Wlr/Wlr、Wlr 必填 wlr_socket_path、pipewire_source:Portal
+ *      明确拒（portal helper 未接）、UInput/Libei 补各自字段、display_no 透传。
+ * 返回 { ok:true, json } 或 { ok:false, error }。
+ */
+function buildLinuxConfig(m, args) {
+  const raw = String(args.config ?? args.target ?? '')
+  if (raw.trim().startsWith('{')) return { ok: true, json: raw.trim() }
+  const decl = (args.linuxDecl && typeof args.linuxDecl === 'object') ? args.linuxDecl : {}
+  const user = (args.linux && typeof args.linux === 'object') ? args.linux : {}
+  /* 双键名：user/linuxDecl 里驼峰与蛇形都认（interface.json 原生是蛇形，daemon 参数是驼峰） */
+  const pickL = (k, k2) => user[k] ?? user[k2] ?? decl[k] ?? decl[k2]
+  const resolveLinuxMethod = (tbl, name) => {
+    if (name === undefined || name === null || name === '') return undefined
+    if (tbl && typeof tbl === 'object' && name in tbl) return Number(tbl[name])
+    const n = Number(name)
+    return Number.isFinite(n) ? n : undefined
+  }
+  const screencapName = pickL('screencap', 'screencap') ?? 'Wlr'
+  const inputName = pickL('input', 'input') ?? 'Wlr'
+  const sc = resolveLinuxMethod(m.LinuxScreencapMethod, screencapName)
+  const im = resolveLinuxMethod(m.LinuxInputMethod, inputName)
+  if (sc === undefined || im === undefined) {
+    return { ok: false, error: 'linux 方法名不合法：screencap=' + screencapName + ' input=' + inputName
+      + '（可选 screencap: Wlr/ExtImage/PipeWire，input: Wlr/UInput/Libei；或直接给 config=<JSON>）' }
+  }
+  const conf = {
+    screencap_method: sc,
+    input_method: im,
+    use_win32_vk_code: !!(user.useWin32VkCode ?? decl.useWin32VkCode ?? decl.use_win32_vk_code),
+  }
+  if (screencapName === 'PipeWire') {
+    const src = pickL('pipewireSource', 'pipewire_source') ?? 'Gamescope'
+    if (src === 'Portal') {
+      return { ok: false, error: 'linux pipewire_source=Portal 暂不支持（portal helper 未接入）——换 Gamescope 或自管 fd' }
+    }
+    conf.pipewire_source = src
+    if (user.pwSocketFd !== undefined) conf.pw_socket_fd = user.pwSocketFd
+    if (user.pwNodeId !== undefined) conf.pw_node_id = user.pwNodeId
+  }
+  if (screencapName === 'Wlr' || inputName === 'Wlr') {
+    const sock = pickL('wlrSocketPath', 'wlr_socket_path')
+    if (!sock) {
+      return { ok: false, error: 'linux 方法含 Wlr：需要 wlr_socket_path（嵌套 compositor 的 socket）——在 linux config JSON 或 interface.json linux{} 里给' }
+    }
+    conf.wlr_socket_path = sock
+  }
+  if (inputName === 'UInput') {
+    if (user.uinputScreenWidth !== undefined) conf.uinput_screen_width = user.uinputScreenWidth
+    if (user.uinputScreenHeight !== undefined) conf.uinput_screen_height = user.uinputScreenHeight
+  }
+  if (inputName === 'Libei') {
+    const eis = pickL('eisSocketPath', 'eis_socket_path')
+    if (eis) conf.eis_socket_path = eis
+  }
+  const dno = pickL('displayNo', 'display_no')
+  if (dno !== undefined) conf.display_no = dno
+  return { ok: true, json: JSON.stringify(conf) }
+}
+
 async function cmdConnect(args) {
   const m = loadMaa()
   if (S.ctrl) { try { S.ctrl.destroy() } catch (e) { /* ignore */ } S.ctrl = null }
+  /* 旧控制器已销毁：分辨率缓存不能留到下一次连接——连接失败时它会是上一台的尺寸，
+   * 让 spaceCheck / stream_status 把旧空间当成当前空间。 */
+  S.fullW = 0; S.fullH = 0
   /* 控制器重建 = 旧流失效：显式停掉并在回执里说明（`streamStopped`），别让调用方以为流还在跑。
    * 曾经的行为是"tick 撞到空控制器后静默死掉、S.stream 仍为 true"，于是重连后的 stream_start 被
    * "已启动"挡回去，表现为一帧都不来（实测：seq 卡死，而 screencap 正常）。 */
@@ -339,13 +478,24 @@ async function cmdConnect(args) {
     /* 指定了 address 却不在已发现列表里：明确报错，不静默连到别的设备上 */
     if (!dev) return { ok: false, error: 'adb 地址 ' + addr + ' 不在已发现设备中（共 ' + adbs.length + ' 台）' }
     const [name, adbPath, address, caps, inputs, config] = dev
+    /* caps/inputs 是 find() 给出的方法位掩码（Uint64 字符串），照原样透传——框架会按
+     * 固定优先级在掩码内自选。仅当 find() 没给时才退 Default（全方法减禁用项），
+     * 不许塞数组：ScreencapOrInputMethods 的绑定类型就是字符串。
+     * agent（maa-node 可选第 6 参）：MXU 传 MaaAgentBinary 路径供 adb 侧 agent；
+     * 声明式 PI 的 agent 桥接走另一条通道（identifier 子进程），这里只透传显式参数。 */
     ctrl = new m.AdbController(adbPath || 'adb', String(address ?? addr),
-      caps && caps.length ? caps : [1, 2], inputs && inputs.length ? inputs : [1, 2], config || '{}')
+      caps || String(m.AdbScreencapMethod?.Default ?? '0'),
+      inputs || String(m.AdbInputMethod?.Default ?? '0'), config || '{}',
+      args.agent ? String(args.agent) : undefined)
     session = { kind: 'adb', target: String(address ?? addr), name: String(name) }
   } else if (args.kind === 'win32' || args.kind === 'gamepad') {
     const wins = await cmdDeviceList('win32')
-    const pick = pickWin32(args.target, wins)
-    if (!pick) {
+    let pick = pickWin32(args.target, wins)
+    /* GamepadController(hwnd|null, gamepad_type, screencap)：规范允许不配图——hwnd=null
+     * 即"仅虚拟手柄输入、不截图"。给了 target 没匹配上仍报错（防静默连错窗口）；
+     * 没给 target 且一个可选窗口都没有时才走 null。 */
+    const gamepadNoWindow = args.kind === 'gamepad' && !pick && !args.target
+    if (!pick && !gamepadNoWindow) {
       return {
         ok: false,
         error: args.target
@@ -362,9 +512,13 @@ async function cmdConnect(args) {
       /* GamepadController 构造器签名（maa-node .d.ts）：(hwnd, gamepad_type, screencap_method)。
          gamepad_type 枚举名→值照 m.GamepadType（Xbox360/DualShock4，缺省 Xbox360）。
          输入走虚拟手柄，需宿主装 ViGEm Bus Driver，否则 connect 会在原生层失败。 */
-      const padType = resolveEnum(m.GamepadType, args.gamepadType, m.GamepadType?.Xbox360 ?? 0, 'gamepadType', warns)
-      ctrl = new m.GamepadController(pick.id, padType, cap)
-      session = { kind: 'gamepad', target: pick.id, name: pick.name || pick.cls, cls: pick.cls, method: { screencap: cap, gamepadType: padType } }
+      const padType = resolveEnum(m.GamepadType,
+        args.gamepadType === 'DS4' ? 'DualShock4' : args.gamepadType,
+        m.GamepadType?.Xbox360 ?? '0', 'gamepadType', warns)
+      ctrl = new m.GamepadController(pick ? pick.id : null, padType, cap)
+      session = { kind: 'gamepad', target: pick ? pick.id : null,
+        name: pick ? (pick.name || pick.cls) : '(无窗口：仅输入)',
+        cls: pick ? pick.cls : null, method: { screencap: cap, gamepadType: padType } }
     } else {
       const mouse = resolveEnum(m.Win32InputMethod, args.mouse, m.Win32InputMethod?.SendMessageWithCursorPos ?? 32, 'mouse', warns)
       const key = resolveEnum(m.Win32InputMethod, args.keyboard, m.Win32InputMethod?.SendMessage ?? 2, 'keyboard', warns)
@@ -378,55 +532,91 @@ async function cmdConnect(args) {
       return { ok: false, error: '控制器类型 ' + args.kind + ' 仅支持在 macOS 上使用；当前宿主是 ' + process.platform }
     }
     if (args.kind === 'playcover') {
-      /* PlayCoverController(address, uuid)：address 是 PlayCover 设备侧服务地址（如 127.0.0.1:port），
-         uuid 是 PlayCover 显示的设备 UUID；两个都必须显式给，猜不了。 */
+      /* PlayCoverController(address, uuid)：address 是设备侧服务地址，uuid 是应用的
+         Bundle Identifier。两者都有缺省（maa-support-extension 同款）：
+         localhost:1717 / maa.playcover——不给 target 也按缺省构造。 */
       const parts = String(args.target ?? '').split('/')
-      const address = parts[0] || ''
-      const uuid = args.uuid ? String(args.uuid) : (parts[1] || '')
-      if (!address || !uuid) {
-        return { ok: false, error: 'playcover 需要 target=<address>/<uuid>（PlayCover 设置里可见，两者都必填）' }
-      }
+      const address = args.address ? String(args.address) : (parts[0] || 'localhost:1717')
+      const uuid = args.uuid ? String(args.uuid) : (parts[1] || 'maa.playcover')
       ctrl = new m.PlayCoverController(address, uuid)
       session = { kind: 'playcover', target: address + '/' + uuid }
     } else {
-      /* MacOSController(window_id, screencap_method, input_method)：窗口用 MacOSController.find() 枚举。 */
+      /* MacOSController(window_id, screencap_method, input_method)：窗口用 MacOSController.find() 枚举。
+         匹配优先级：target（id 或标题子串）> macosTitleRegex（PI title_regex）> 第一个窗口。 */
       const wins = (await m.MacOSController.find()) || []
-      const pick = args.target
-        ? (wins.find((d) => String(d[0]) === String(args.target)) ??
-           wins.find((d) => String(d[2] ?? '').includes(String(args.target))))
-        : (wins[0] ?? null)
+      let pick = null
+      if (args.target) {
+        pick = wins.find((d) => String(d[0]) === String(args.target)) ??
+               wins.find((d) => String(d[2] ?? '').includes(String(args.target)))
+      } else if (args.macosTitleRegex) {
+        let re = null
+        try { re = new RegExp(String(args.macosTitleRegex)) } catch (e) { /* 坏正则按下个分支报错 */ }
+        if (re) pick = wins.find((d) => re.test(String(d[2] ?? '')))
+        else return { ok: false, error: 'macos title_regex 不是合法正则：' + args.macosTitleRegex }
+      } else {
+        pick = wins[0] ?? null
+      }
       if (!pick) {
-        return { ok: false, error: args.target ? 'macOS 窗口未找到：' + args.target : '未发现 macOS 窗口' }
+        return { ok: false, error: args.target ? 'macOS 窗口未找到：' + args.target
+          : args.macosTitleRegex ? 'macOS 窗口按 title_regex 未匹配到：' + args.macosTitleRegex
+          : '未发现 macOS 窗口' }
       }
-      const cap = resolveEnum(m.MacOSScreencapMethod, args.screencap, m.MacOSScreencapMethod?.ScreenCaptureKit ?? 2, 'screencap', warns)
-      const input = resolveEnum(m.MacOSScreencapMethod, args.keyboard, m.MacOSScreencapMethod?.ScreenCaptureKit ?? 2, 'keyboard', warns)
+      const cap = resolveEnum(m.MacOSScreencapMethod, args.screencap, m.MacOSScreencapMethod?.ScreenCaptureKit ?? '1', 'screencap', warns)
+      /* input 走 MacOSInputMethod 表（GlobalEvent/PostToPid），缺省 GlobalEvent(1)——
+       * 此前误用了 screencap 表+keyboard 参数，名字解析必错（ScreenCaptureKit 值恰好是 '1' 才没炸）。 */
+      const input = resolveEnum(m.MacOSInputMethod, args.input, m.MacOSInputMethod?.GlobalEvent ?? '1', 'input', warns)
       ctrl = new m.MacOSController(pick.id ?? pick[0], cap, input)
       session = { kind: 'macos', target: String(pick[0]), name: String(pick[2] ?? ''), method: { screencap: cap, input } }
     }
   } else if (args.kind === 'linux') {
-    /* LinuxController(config JSON)：wlroots / PipeWire / uinput / Libei 会话按配置串交给本体。
-       config 必须显式给（含 screencap_method / input_method 等必填字段），工具不猜会话形态。 */
     if (process.platform !== 'linux') {
       return { ok: false, error: '控制器类型 linux 仅支持在 Linux 上使用；当前宿主是 ' + process.platform }
     }
-    const cfg = String(args.config ?? args.target ?? '')
-    if (!cfg.trim().startsWith('{')) {
-      return { ok: false, error: 'linux 控制器需要 config=<JSON>（screencap_method/input_method 必填；wlroots 要 wlr_socket_path，PipeWire 要 pw_socket_fd+pw_node_id 等）' }
-    }
-    ctrl = new m.LinuxController(cfg)
+    const cfg = buildLinuxConfig(m, args)
+    if (cfg.ok === false) return { ok: false, error: cfg.error }
+    ctrl = new m.LinuxController(cfg.json)
     session = { kind: 'linux', target: '(config)' }
   } else {
     return { ok: false, error: '未知控制器类型：' + args.kind + '（支持 win32/adb/gamepad/playcover/macos/linux）' }
   }
   /* 截图缩放目标：默认不干预 —— maafw 本体按 interface.json 的 short_side（缺省最短边 720p）缩放。
-   * 只有用户显式传参才覆盖；注意这会改变 Tasker 识别图像的尺寸（模板/ROI 坐标系随之变化）。 */
+   * 只有用户显式传参才覆盖；注意这会改变 Tasker 识别图像的尺寸（模板/ROI 坐标系随之变化）。
+   * display_* 四种模式互斥（MXU DisplayOptions.validate 同款规则）：rawSize / expand / longSide
+   * / shortSide 只允许给一个，多给是配置错误——静默多设几个 setter 的覆盖顺序不可观测，直接拒。 */
+  const displayModes = [!!args.rawSize, !!args.expand, !!args.longSide, !!args.shortSide].filter(Boolean).length
+  if (displayModes > 1) {
+    try { ctrl.destroy() } catch (e) { /* ignore */ }
+    return { ok: false, error: 'display_* 互斥：rawSize / expand / longSide / shortSide 只能给一个（同时声明了 ' + displayModes + ' 个）' }
+  }
   try {
-    if (args.shortSide) ctrl.screenshot_target_short_side = Number(args.shortSide)
-    if (args.longSide) ctrl.screenshot_target_long_side = Number(args.longSide)
     if (args.rawSize) ctrl.screenshot_use_raw_size = true
+    else if (args.expand) {
+      const [ew, eh] = Array.isArray(args.expand) ? args.expand : []
+      if (!Number.isFinite(ew) || !Number.isFinite(eh) || ew <= 0 || eh <= 0) {
+        try { ctrl.destroy() } catch (e) { /* ignore */ }
+        return { ok: false, error: 'display_expand 需要两个正整数 [w,h]：' + JSON.stringify(args.expand) }
+      }
+      ctrl.screenshot_target_expand = [Number(ew), Number(eh)]
+    } else if (args.longSide) ctrl.screenshot_target_long_side = Number(args.longSide)
+    else if (args.shortSide) ctrl.screenshot_target_short_side = Number(args.shortSide)
   } catch (e) { /* 绑定版本不支持 setter 时忽略 */ }
+  /* 连接判定：5.14.2 实测 `Job.wait()` 在连接失败时**不抛异常**，只把 status 置为 Failed（4000）。
+   * 不查 status 就会把失败当成功：S.ctrl/S.session 照设、connect 回 ok:true，下一条命令再踩
+   * 半残控制器（预热截图失败只写进 resolution.error，CLI 摘要里看不出来）。 */
+  let connJob = null
+  try {
+    connJob = ctrl.post_connection()
+    await connJob.wait()
+  } catch (e) {
+    try { ctrl.destroy() } catch (e2) { /* ignore */ }
+    return { ok: false, error: '连接失败：' + String(e && e.message || e) }
+  }
+  const connStatus = Number(connJob && connJob.status)
+  if (connStatus !== STATUS.succeeded) {
+    try { ctrl.destroy() } catch (e) { /* ignore */ }
+    return { ok: false, error: '连接失败：post_connection status=' + String(connStatus) + '（成功应为 ' + STATUS.succeeded + '）' }
+  }
   S.ctrl = ctrl
-  await ctrl.post_connection().wait()
   S.session = session
   S.connGen++
   /* 预热一次截图，取控制器分辨率（默认短边 720 的坐标系，pipeline 的 roi/模板即此空间） */
@@ -452,6 +642,8 @@ async function cmdDisconnect() {
   if (S.stream) await cmdStreamStop()
   await cleanupAgents()
   if (S.tasker) { try { S.tasker.destroy() } catch (e) { /* ignore */ } S.tasker = null }
+  /* tasker 收掉之后再放 Resource：顺序反了会让还在引用的 tasker 拿到已销毁的句柄 */
+  if (S.runRes) { try { S.runRes.destroy() } catch (e) { /* ignore */ } S.runRes = null }
   if (S.ctrl) { try { S.ctrl.destroy() } catch (e) { /* ignore */ } S.ctrl = null }
   S.session = null
   return { ok: true }
@@ -574,19 +766,26 @@ function pushFrame(dec, png) {
     S.quietNow = false
     const last = S.events.length ? S.events[S.events.length - 1] : null
     if (last && last.type === 'change' && fr.t - last.t < 400) {
+      /* 合并同簇：seq/t/diff 前移，**frame 锚点必须跟着前移**——否则事件指向的是簇内第一帧，
+       * 而调用方看到的 t/seq 是最后一帧，锚点与内容对不上（同一类"回执与事实不符"）。 */
       last.t = fr.t; last.seq = fr.seq; last.diff = Math.max(last.diff, diff)
+      l0AnchorAdd({ ...l0, source: 'change' })
+      last.frame = eventFrameAnchor(fr.seq)
     } else {
+      /* 顺序要紧：**先入锚区、再发事件**。事件里的 `frame.retained` 是按 seq 反查 L0 得出的，
+       * 反过来的话刚发出的 change/stable 事件会自报 `retained:'gone'`——明明它自己就是
+       * 触发入锚区的那一帧（实测就是这么错了一次）。 */
+      l0AnchorAdd({ ...l0, source: 'change' })
       pushEvent({
         type: 'change', seq: fr.seq, t: fr.t, diff: Math.round(diff * 1000) / 1000,
         ...(changed ? { blocks: changed.blocks.length, region: changed.region } : {}),
       })
-      l0AnchorAdd({ ...l0, source: 'change' })
     }
   } else if (prev) {
     if (!S.quietNow) {
       S.quietNow = true
-      pushEvent({ type: 'stable', seq: fr.seq, t: fr.t, diff: Math.round(diff * 1000) / 1000 })
       l0AnchorAdd({ ...l0, source: 'stable' })
+      pushEvent({ type: 'stable', seq: fr.seq, t: fr.t, diff: Math.round(diff * 1000) / 1000 })
     }
   }
 }
@@ -594,7 +793,29 @@ function pushFrame(dec, png) {
  * 主动抓一张原图并入观测流（seq 前进、进环、进 L0，可作动作/run 边界锚点）。
  * 采集失败如实上报，绝不阻断调用方的动作——动作结果与留存失败分别报告（契约 §9）。
  */
-async function captureNow(source) {
+/**
+ * 动作回执帧落盘：一次性 CLI（daemon 随命令死）也能复核"动作前后画面"——
+ * 帧本身是 L0 原图字节，落 runDir/action-frames/（与关键帧库分开：这不是留存证据本体，
+ * 是回执附件，不占 kf 配额、不进 manifest）。
+ * 同一次 input 的 before/after 用同一对文件名；dir 不存在则跳过（静默降级为无路径回执）。
+ */
+function actionFramesRoot() {
+  return S.runDir ? path.join(S.runDir, 'action-frames') : null
+}
+function persistActionFrame(seq, source) {
+  const root = actionFramesRoot()
+  if (!root) return null
+  const ent = S.l0.roll.find((e) => e.seq === seq)
+  if (!ent || !ent.png) return null
+  try {
+    fs.mkdirSync(root, { recursive: true })
+    const file = path.join(root, source + '-seq' + String(seq).padStart(6, '0') + '.png')
+    fs.writeFileSync(file, ent.png)
+    return file
+  } catch (e) { return null }
+}
+
+async function captureNow(source, persist = false) {
   if (!S.ctrl) return { ok: false, error: '未连接设备' }
   try {
     const j = S.ctrl.post_screencap()
@@ -606,37 +827,80 @@ async function captureNow(source) {
     pushFrame(dec, b)
     const ent = S.l0.roll[S.l0.roll.length - 1]
     l0AnchorAdd({ ...ent, source }, true)
-    return { ok: true, seq: ent.seq, t: ent.t, w: ent.w, h: ent.h }
+    const out = { ok: true, seq: ent.seq, t: ent.t, w: ent.w, h: ent.h }
+    /* 动作帧持久化：一次性 CLI 下 seq 无消费者（daemon 死后 frame_get 不存），
+     * 路径才是回执里能看的东西；常驻会话里多写一份也无害（同字节、幂等文件名）。 */
+    if (persist) {
+      const file = persistActionFrame(ent.seq, source)
+      if (file) out.file = file
+    }
+    return out
   } catch (e) {
     return { ok: false, error: String(e && e.message || e) }
   }
 }
 
 /**
- * 用控制器缓存图入锚区（node-ok/fail 锚点的实现方式）。
+ * node-ok/fail 锚点：用控制器缓存图入锚区，带"上一张已留帧的 hash"去重。
  * 关键约束：不要在节点回调里发 post_screencap——add_sink 回调中并发截图会与 Tasker
  * 识别回路竞争控制器，实测触发原生崩溃 0xC0000005（maa-node 5.14.2 win32-x64，
  * 2026-10-05 真机：同任务关锚点正常 / 开锚点必崩）。
  * cached_image 是框架识别回路自己截的图：零新任务、无竞争，且节点回调时刻的缓存
  * 通常就是该节点识别所用的那张（bound 倾向）；但下一节点识别可能已刷新缓存，
- * 关联强度按 adjacent 报，不冒称 bound（契约 §4）。 */
-function anchorFromCache(source) {
-  if (!S.ctrl) return
+ * 关联强度按 adjacent 报，不冒称 bound（契约 §4）。
+ * 节点结束帧若与上一张已留帧相同（hashDist < NODE_FRAME_DEDUP）就不重复入锚区，
+ * 返回 { seq:null, skipped:'same' }；不同则入锚区并返回 { seq, hash }（调用方拿 hash 记给下一次）。
+ * 阈值取小：目标是"同一个屏重复出现只留一张"，不是"相似就丢"——近似画面各自留，别误并。
+ */
+const NODE_FRAME_DEDUP = 0.02
+function anchorFromCacheDedup(source, lastHash) {
+  if (!S.ctrl) return { seq: null, skipped: 'no-ctrl' }
   let img = null
-  try { img = S.ctrl.cached_image } catch (e) { return }
-  if (!img || img.byteLength < 9) return
+  try { img = S.ctrl.cached_image } catch (e) { return { seq: null, skipped: 'no-img' } }
+  if (!img || img.byteLength < 9) return { seq: null, skipped: 'no-img' }
   const b = Buffer.from(img)
   let dec = null
-  try { dec = pngDecode(b) } catch (e) { return }
+  try { dec = pngDecode(b) } catch (e) { return { seq: null, skipped: 'decode' } }
+  const rgb = toRgb(dec)
+  const h = blockHash(rgb, dec.w, dec.h)
+  if (lastHash && hashDist(lastHash, h) < NODE_FRAME_DEDUP) return { seq: null, skipped: 'same' }
   pushFrame(dec, b)
   const ent = S.l0.roll[S.l0.roll.length - 1]
   l0AnchorAdd({ ...ent, source }, true)
+  return { seq: ent.seq, hash: h }
 }
-/** 事件入环 + 推送 host（cap 1200） */
+/** 事件入环 + 推送 host（cap 1200）。
+ *
+ * 事件自带 `frame` 锚点：告诉调用方"这一刻的画面在哪能拿到"。
+ * 为什么必须有：事件流的消费者（LLM / 脚本）看到 `{"type":"stable","seq":2,"diff":0}` 时，
+ * 唯一想知道的是"那是什么画面"——旧回执只有 seq/t/diff，人得自己去 `frame get 2` 试，
+ * 而 L0 是**滚动淘汰**的，试的时候那张图可能已经没了（本仓 G9：事件无画面锚点，
+ * 只能拿 seq 去撞运气）。现在按 seq 反查 L0 两区，直接给出可取性：
+ *
+ *   frame: { seq, retained: 'l0' | 'gone', source }   // retained='l0' 才能 frame get / kf promote
+ *
+ * 只报事实，不代取图：取图要走 `frame get`（`--src full` 出控制器分辨率原图），
+ * 事件里塞 PNG 会让 1200 条环形缓冲变成内存炸弹。 */
+function eventFrameAnchor(seq) {
+  if (typeof seq !== 'number') return undefined
+  const inRoll = S.l0.roll.find((x) => x.seq === seq)
+  const inAnchor = S.l0.anchor.find((x) => x.seq === seq)
+  const hit = inRoll ?? inAnchor
+  if (!hit) return { seq, retained: 'gone' }
+  return {
+    seq,
+    retained: 'l0',
+    /* 两区都可能有同一 seq（共享 Buffer）：优先报锚区来源（锚区才是"值得留的"那张） */
+    source: (inAnchor ?? inRoll).source ?? null,
+    w: hit.w, h: hit.h,
+  }
+}
+
 function pushEvent(ev) {
-  S.events.push(ev)
+  const anchored = { ...ev, frame: eventFrameAnchor(ev.seq) }
+  S.events.push(anchored)
   if (S.events.length > 1200) S.events.splice(0, S.events.length - 1200)
-  send({ kind: 'event', ev })
+  send({ kind: 'event', ev: anchored })
 }
 
 async function streamTick() {
@@ -702,6 +966,36 @@ function cmdStreamStatus() {
   }
 }
 
+/**
+ * 事件环查询（顶层 CLI 用）。
+ *
+ * 为什么必须做成 daemon 命令：事件环 `S.events` 活在 daemon 进程里，而一次性 CLI 命令
+ * **退出即断连**——它拿不到"过去发生过什么"，只能自己开着会话边跑边收。于是本仓 G7 的
+ * 诉求（`events` 不该只在 repl 里）落不到"客户端本地环"上，只能让 daemon 按需吐出它自己那份。
+ *
+ * 与 REPL 的 `events` 是**同一份数据**（同一个 `S.events`），只是取用方式不同：
+ * REPL 边收推送边留本地副本，CLI 每次现查。两处渲染共用 `frame` 锚点字段。
+ *
+ * `since` 支持按 seq 增量拉取（长跑时反复查询不必重传全量）；`limit` 从尾部截取。
+ */
+function cmdEventsList(args) {
+  const rawSince = Number(args.since)
+  const since = Number.isFinite(rawSince) ? rawSince : null
+  const rawLimit = Number(args.limit)
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.floor(rawLimit) : 20
+  const all = since === null ? S.events : S.events.filter((e) => typeof e.seq === 'number' && e.seq > since)
+  const picked = all.slice(-limit)
+  return {
+    ok: true,
+    /* 报总数与"环里还留着多少"，让调用方知道有没有被 1200 上限截掉过 */
+    total: S.events.length,
+    matched: all.length,
+    cap: 1200,
+    truncated: all.length > picked.length,
+    events: picked,
+  }
+}
+
 /* ────────────────────────── 历史帧取用（ROI 裁剪，像素按需出 worker） ────────────────────────── */
 /**
  * roi 参数校验：只接受 4 个**有限数字**。
@@ -782,6 +1076,9 @@ function cmdFrameGet(args) {
       return {
         ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: rw, h: rh,
         seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: full.w, ctrlH: full.h,
+        /* 帧身份：观测面 blockHash 的 64bit 串——input 的 expectFrame 拿它核对
+         * "现在这帧还是不是我当初看到的那帧"。同 seq 的两帧 hash 必同（同一份像素）。 */
+        frameHash: hashStr(fr.hash),
         source: 'l0-full', sourceResolution: 1, degraded: false,
         requested: { w, h },
       }
@@ -830,6 +1127,7 @@ function cmdFrameGet(args) {
     return {
       ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: full.w, h: full.h,
       seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: full.w, ctrlH: full.h,
+      frameHash: hashStr(fr.hash),
       source: 'l0-full', sourceResolution: 1,
     }
   }
@@ -840,6 +1138,7 @@ function cmdFrameGet(args) {
   return {
     ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: fr.w, h: fr.h,
     seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: fr.fw, ctrlH: fr.fh,
+    frameHash: hashStr(fr.hash),
     source: 'l1-ring', sourceResolution: sx0,
     /* 整帧小图是**文档写明的缺省行为**，不是降级：只标注来源与分辨率，不警告、不判 findings——
      * 否则最普通的 `frame get`（不带 roi）会时不时退 3。要原图就显式 `--src full`。 */
@@ -968,26 +1267,54 @@ function cmdFrameDiff(args) {
 }
 
 /* ────────────────────────── 资源 / 运行 / 识别 ────────────────────────── */
-async function ensureResource(dir) {
-  if (!S.res) {
-    const m = loadMaa()
-    S.res = new m.Resource()
-  }
-  if (dir) await S.res.post_bundle(dir).wait()
-  return S.res
-}
 /**
- * 项目驱动的多路径资源：interface.json 的 resource.path[] + attach_resource_path
- * 按顺序叠加、后者覆盖前者（MaaPiCli Configurator 的语义），对应逐个 post_bundle。
- * 每次运行都新建 Resource——复用旧实例会把上一次运行的 bundle 残留进来
- * （比如上次加载了皮肤包这次没选，残留会让 override 关系错乱）。
+ * 资源加载的唯一入口：`dirs` 是整条链（`resource.path[]` + attach，按序叠加、后者覆盖前者，
+ * 对应逐个 `post_bundle`），单包就是长度为 1 的链。
+ *
+ * **每次都新建 Resource**：`post_bundle` 是叠加语义，复用旧实例会把上一次运行的 bundle 残留进来
+ * （上次加载了皮肤包这次没选，残留会让 override 关系错乱）；单包若复用会话资源，长活会话里
+ * `run --resource-dir B` 还会带着上一轮 A 的节点/模板跑。会话不该有一份"当前资源"的共享态。
  */
-async function buildResource(dirs) {
+async function buildResource(dirs, hashCheck) {
   const m = loadMaa()
   const res = new m.Resource()
-  for (const d of dirs) await res.post_bundle(d).wait()
+  /* hashCheck：PI v2.6 的 resource.hash 校验，时机是"只加载完 path[]"（attach_resource_path
+   * 不能算进被校验对象）。两段在 plan 侧已分好：pathDirs 是资源自己的声明路径，
+   * attachDirs 是控制器追加段；dirs 兜底=全链（无校验声明时调用方不传 hashCheck）。
+   * 读出的实际值写回 hashCheck.actual——校验结果（匹配/不匹配）由调用方决定怎么报。 */
+  const pathDirs = hashCheck ? hashCheck.pathDirs : dirs
+  /* plan 侧 paths 做了整体去重（attach 若与 path 相同会消失），这里保持同一份：
+   * attach 去重掉已在 pathDirs 里的项，保证加载序列与 paths 一一对应 */
+  const attachDirs = hashCheck ? hashCheck.attachDirs.filter((d) => !pathDirs.includes(d)) : []
+  try {
+    for (const d of pathDirs) await res.post_bundle(d).wait()
+    if (hashCheck) hashCheck.actual = res.hash || ''
+    for (const d of attachDirs) await res.post_bundle(d).wait()
+  } catch (e) {
+    /* 加载中途失败也要把句柄收掉：否则每次失败的 run 都在 native 侧留一份 */
+    try { res.destroy() } catch (e2) { /* ignore */ }
+    throw e
+  }
   return res
 }
+
+/**
+ * 换掉"最近一次 run / --act 的 Resource"并销毁上一份。
+ *
+ * 每次新建保证了资源隔离（单包不再叠上一轮 bundle），但 native 句柄必须有释放点——否则长活
+ * REPL 里每 run 一次就多留一份（OCR 模型尤其重）。
+ *
+ * **调用前提由调用方保证**，不在这里重试：(1) 没有任务在飞（`cmdRun` 开头有 `runActive` 守卫、
+ * `reco --act` 自己拒绝运行中的任务）；(2) `tasker.resource` 已指向新对象。满足这两条才能立刻
+ * 销毁上一份——早于 (2) 销毁会让 tasker 拿着死句柄，晚于 (1) 会踩到正在跑的任务。
+ */
+function adoptRunResource(res) {
+  const prev = S.runRes
+  S.runRes = res
+  if (!prev || prev === res) return
+  try { prev.destroy() } catch (e) { /* ignore */ }
+}
+
 function ensureTasker() {
   if (!S.tasker) {
     const m = loadMaa()
@@ -1000,35 +1327,113 @@ function ensureTasker() {
  * 模式照 maa-support-extension 的 setupAgent：new Client() 自动生成 identifier，
  * 把 identifier 追加为子进程最后一个参数（agent 侧 sys.argv[-1] → AgentServer.start_up），
  * bind_resource 后 connect（与子进程退出/超时竞速）。custom action/recognition 经此
- * 注册进绑定的 Resource——依赖 agent 的节点（M9A DisableNode 等）由此可用。 */
+ * 注册进绑定的 Resource——依赖 agent 的节点（M9A DisableNode 等）由此可用。
+ *
+ * 环境变量：调用方给的 `PI_*` 原样并入子进程 env。本层不解释取值也不补默认——
+ * 协议允许逐项缺省、由 agent 容错；这里编一个默认值只会把"没注入"伪装成"注入了"。 */
+/* 收掉整棵 agent 进程树。真身在子孙层（uv run → venv-python → uv-python agent/main.py），
+ * child.kill() 只到直接子进程（uv.exe）。顺序是硬约束：必须先杀再 disconnect——
+ * disconnect 会让 uv.exe 自己优雅退出，它的 python 子孙瞬间脱离父链，taskkill /T
+ * 再够不到（实测 disconnect 在先必留两个 python 孤儿）。
+ *
+ * 两刀：① taskkill /T /F 按父链整棵收（够用，但 uv 在 kill 途中重 exec 出的孙级
+ * 会漏）；② 用 identifier 扫命令行兜底——agent 树每层 argv 都带同一个
+ * identifier（sys.argv[-1]），一次 -like 点名全树，与父子链无关。
+ * 第②刀的 $PID 排除自身：否则 -like 会命中这个 powershell 自己的 CommandLine
+ * （字面量里带着 ident），自杀在中途把 python 留成孤儿（实测）。POSIX 用
+ * detached 进程组（spawn 时 detached:true），负 pid 杀整组。 */
+function killTree(child, ident) {
+  if (!child || !child.pid) return Promise.resolve()
+  if (process.platform === 'win32') {
+    const root = child.pid
+    /* taskkill /T 收父链 + identifier 兜底：agent 树每层 argv 都带同一个 identifier
+     * （sys.argv[-1]），一次 -like 点名全树，与父子链无关——taskkill 杀 uv.exe 时它
+     * 重 exec 出的孙级会漏，这层兜住。$PID 排除自身：-like 会命中这个 powershell 自己
+     * 的 CommandLine（字面量里带着 ident），自杀在中途把 python 留成孤儿（实测）。 */
+    /* 一刀 taskkill 按父链收 + 一刀 ident sweep 点名全树（agent 每层 argv 带同一个
+     * identifier，与父子链无关——taskkill 杀 uv.exe 时它重 exec 出的中层 venv-python
+     * 会漏，这层兜住）。$PID 排除自身：-like 会命中这个 powershell 自己的 CommandLine
+     * （字面量里带着 ident），自杀在中途把 python 留成孤儿（实测）。两刀都 await：
+     * fire-and-forget 会让 daemon 在 sweep 还没跑完就 exit，python 照样孤儿。 */
+    const sweep = () => new Promise((resolve) => {
+      const like = '%' + String(ident || '').replace(/'/g, '') + '%'
+      const ps =
+        '$self=' + '$PID;' +
+        `Get-CimInstance Win32_Process | Where-Object { $_.ProcessId -ne $self -and $_.CommandLine -and $_.CommandLine -like '${like}' } |` +
+        'ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue } catch {} };' +
+        'try { Stop-Process -Id ' + root + ' -Force -ErrorAction SilentlyContinue } catch {}'
+      try { execFile('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps], { timeout: 30000 }, () => resolve()) } catch (e) { resolve() }
+    })
+    const kill = () => new Promise((resolve) => {
+      try {
+        execFile('taskkill', ['/pid', String(root), '/T', '/F'], { timeout: 10000 }, () => resolve())
+      } catch (e) {
+        try { child.kill() } catch (e2) { /* ignore */ }
+        resolve()
+      }
+    })
+    return kill().then(() => sweep())
+  }
+  try { process.kill(-child.pid, 'SIGKILL') } catch (e) {
+    try { child.kill('SIGKILL') } catch (e2) { /* ignore */ }
+  }
+  return Promise.resolve()
+}
+
 async function cleanupAgents() {
   const bind = S.agentBind
   S.agentBind = null
   if (!bind) return
   for (const c of bind.clients) {
+    /* 先树杀、后 disconnect：顺序反过来 disconnect 会抢先让 uv.exe 退掉，子孙脱离
+     * 父链后 taskkill /T 够不到（实测留两个 python 孤儿）。 */
+    try { process.stderr.write('[cleanupAgents] kill ' + (c.child && c.child.pid) + ' ident=' + c.ident + '\n') } catch (e) { /* ignore */ }
+    await killTree(c.child, c.ident)
     try { c.client.disconnect() } catch (e) { /* ignore */ }
     try { c.client.destroy() } catch (e) { /* ignore */ }
-    try { c.child.kill() } catch (e) { /* ignore */ }
   }
 }
 
-async function setupAgents(res, decls, cwd) {
+async function setupAgents(res, decls, cwd, piEnv, sinks, maaMod, spawnFn) {
   const key = JSON.stringify(decls)
   if (S.agentBind && S.agentBind.res === res && S.agentBind.key === key) {
     const alive = S.agentBind.clients.every((c) => {
       try { return c.client.connected && c.client.alive } catch (e) { return false }
     })
-    if (alive) return { ok: true, reused: true, clients: S.agentBind }
+    if (alive) return { ok: true, reused: true, clients: S.agentBind, sinks: S.agentBind.sinks }
   }
   await cleanupAgents()
-  const m = loadMaa()
+  const m = maaMod ?? loadMaa()
+  const doSpawn = spawnFn ?? spawn
   const clients = []
+  /* sink 注册是桥接的另一半：只 bind_resource 时 agent 侧 context.tasker.controller /
+   * context.tasker 发出的 reverse request 会带空 controller_id / 找不到 tasker，
+   * 框架日志报 controller not found 后 custom action 挂起（实测：patrol 的 post_click
+   * 静默失败，角色原地等死）。三个 sink 必须在 connect() 之前注册。 */
+  const sinkDefs = [
+    ['resource', sinks && sinks.resource, 'register_resource_sink'],
+    ['controller', sinks && sinks.controller, 'register_controller_sink'],
+    ['tasker', sinks && sinks.tasker, 'register_tasker_sink'],
+  ]
   for (const d of decls) {
-    const client = new m.Client()
+    /* interface 声明固定 identifier 时原样交给 Client（schema：socket 同名，断线可重连）。
+     * 代价：残留旧 socket 时 connect 会等满超时才败——项目声明了就是它要的语义，照做。 */
+    const client = new m.Client(typeof d.identifier === 'string' && d.identifier ? d.identifier : undefined)
     const ident = client.identifier
     let child = null
     try {
-      child = spawn(d.exec, [...d.args, ident], { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+      const env = piEnv && typeof piEnv === 'object' ? Object.fromEntries(
+        Object.entries(piEnv).filter(([, v]) => typeof v === 'string' && v !== ''),
+      ) : {}
+      child = doSpawn(d.exec, [...d.args, ident], {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        /* POSIX 下脱离父进程组：killTree 靠负 pid 杀整组；Windows 无进程组概念，taskkill /T 兜底 */
+        ...(process.platform !== 'win32' ? { detached: true } : {}),
+        /* 空对象时干脆不传 env（子进程照常继承），别用空 env 覆盖掉 PATH */
+        ...(Object.keys(env).length ? { env: { ...process.env, ...env } } : {}),
+      })
     } catch (e) {
       try { client.destroy() } catch (e2) { /* ignore */ }
       return { ok: false, error: 'agent 子进程启动失败：' + d.exec + '（' + String(e && e.message || e) + '）' }
@@ -1043,12 +1448,27 @@ async function setupAgents(res, decls, cwd) {
       try { client.destroy() } catch (e2) { /* ignore */ }
       return { ok: false, error: 'agent 绑定资源失败：' + String(e && e.message || e) }
     }
+    const sinksRegistered = []
+    const sinkErrs = []
+    for (const [name, obj, method] of sinkDefs) {
+      if (!obj) continue
+      try { client[method](obj); sinksRegistered.push(name) } catch (e) {
+        sinkErrs.push(name + '：' + String(e && e.message || e))
+      }
+    }
+    client.__sinks = { registered: sinksRegistered, ...(sinkErrs.length ? { errors: sinkErrs } : {}) }
+    /* sink 注册失败不阻断：custom action 不碰 context.controller/tasker 的项目照跑，
+     * 但回执必须点名哪一项没注上——半残不报就是"controller not found"那种排障半天。 */
     const exited = new Promise((r) => child.on('exit', () => r('exit')))
+    let timer = null
     const ok = await Promise.race([
       client.connect().then(() => 'ok', () => 'err'),
       exited,
-      sleep(60000).then(() => 'timeout'),
+      new Promise((r) => { timer = setTimeout(() => r('timeout'), 60000) }),
     ])
+    /* connect 或子进程退出先赢时把超时就地收掉：不然这个 setTimeout 挂着 60s
+     * 才让进程退（headless 调用方——比如单测——会被它拖住）。 */
+    if (timer) clearTimeout(timer)
     /* connect() resolve 不代表可用：协议版本错配（maa-node 与 agent 侧 maa 版本不一致）时
      * 通道建立但握手被拒——必须复核 connected && alive（maa-support 同款检查）。 */
     let usable = ok === 'ok'
@@ -1062,14 +1482,19 @@ async function setupAgents(res, decls, cwd) {
       try { child.kill() } catch (e) { /* ignore */ }
       return { ok: false, error: 'agent ' + why + '：' + [d.exec, ...d.args].join(' ') + '；输出尾部：' + out.slice(-300) }
     }
-    clients.push({ client, child, name: [d.exec, ...d.args].join(' '), out })
+    clients.push({ client, child, ident, name: [d.exec, ...d.args].join(' '), out })
+  }
+  /* 汇总所有 client 的 sink 结果：registered 取并集，errors 逐条带上是哪个 agent */
+  const sinkReport = {
+    registered: [...new Set(clients.flatMap((c) => c.client.__sinks?.registered ?? []))],
+    errors: clients.flatMap((c) => (c.client.__sinks?.errors ?? []).map((e) => c.name + '：' + e)),
   }
-  S.agentBind = { res, key, clients }
+  S.agentBind = { res, key, clients, sinks: sinkReport }
   let actions = null
   let recos = null
   try { actions = clients[0].client.custom_action_list } catch (e) { /* ignore */ }
   try { recos = clients[0].client.custom_recognition_list } catch (e) { /* ignore */ }
-  return { ok: true, clients: S.agentBind, actions, recos }
+  return { ok: true, clients: S.agentBind, actions, recos, sinks: sinkReport }
 }
 
 const sab = new Int32Array(new SharedArrayBuffer(4))
@@ -1087,37 +1512,87 @@ function pickNodeName(m) {
   return { name: String(m.name || ('node#' + m.node_id)), source: 'entry' }
 }
 
+/** 识别半：从带 node_id 的通知里抽识别框——没有它 record.nodes 只有"哪个节点跑过"，
+ * 不知道"这一步看的是哪个元素"（示范轨迹缺口 #1）。字段全防御性取（不同版本字段会缺），
+ * 一条都取不到就返回 null、不挂空对象。 */
+function pickRecoBox(m) {
+  const d = m.reco_details
+  if (!d || typeof d !== 'object') return null
+  const o = {}
+  if (d.name !== undefined) o.name = String(d.name)
+  if (d.algorithm !== undefined) o.algorithm = String(d.algorithm)
+  if (d.hit !== undefined) o.hit = !!d.hit
+  if (Array.isArray(d.box) && d.box.length === 4) o.box = d.box.map(Number)
+  /* detail.best.score 是命中质量分（TemplateMatch 有，OCR 没有）——能拿到就带，拿不到不编 */
+  const best = d.detail && typeof d.detail === 'object' && !Array.isArray(d.detail) ? d.detail.best : null
+  if (best && typeof best === 'object' && best.score !== undefined) o.score = Number(best.score)
+  return Object.keys(o).length ? o : null
+}
+
+/** 动作半：动作的落点框（action_details.box 是实际动作框，success 是动作自身成败）。 */
+function pickActionBox(m) {
+  const d = m.action_details
+  if (!d || typeof d !== 'object') return null
+  const o = {}
+  if (d.name !== undefined) o.name = String(d.name)
+  if (d.action !== undefined) o.action = String(d.action)
+  if (d.success !== undefined) o.success = !!d.success
+  if (Array.isArray(d.box) && d.box.length === 4) o.box = d.box.map(Number)
+  return Object.keys(o).length ? o : null
+}
+
 async function cmdRun(args) {
   if (!S.ctrl) return { ok: false, error: '未连接设备（先 maa_connect）' }
   if (S.runActive) return { ok: false, error: '已有任务在运行（先 maa_run_stop）' }
-  let res
-  if (Array.isArray(args.resourceDirs) && args.resourceDirs.length) {
-    res = await buildResource(args.resourceDirs.map(String))
-    S.res = res
-  } else {
-    if (!args.resourceDir) return { ok: false, error: '缺少 resourceDir（或 resourceDirs 数组）' }
-    res = await ensureResource(args.resourceDir)
-  }
+  const resDirs = Array.isArray(args.resourceDirs) && args.resourceDirs.length
+    ? args.resourceDirs.map(String)
+    : (args.resourceDir ? [String(args.resourceDir)] : [])
+  if (!resDirs.length) return { ok: false, error: '缺少 resourceDir（或 resourceDirs 数组）' }
+  /* 上一轮的 agent 子进程与 Resource 在这里收掉：走到这行必然没有任务在飞（runActive 守卫），
+   * 这一轮也不存在可复用的资源对象。放在参数校验之后——调用参数错了不该把上一份资源也丢掉。 */
+  /* 上一轮 agent 子进程先断掉：这一轮会新建 Resource，绑定不可能复用。 */
+  await cleanupAgents()
+  const hashCheck = args.resourceHashCheck && typeof args.resourceHashCheck === 'object' ? args.resourceHashCheck : null
+  const res = await buildResource(resDirs, hashCheck)
+  /* v2.6 一致性校验：不匹配只警告不阻断（协议原文"不应阻止继续使用"），结果如实进回执与 warns */
+  const runWarns = []
+  if (hashCheck && hashCheck.expected !== undefined) {
+    hashCheck.match = hashCheck.actual === hashCheck.expected
+    if (!hashCheck.match) {
+      runWarns.push('资源完整性校验失败：' + String(hashCheck.resourceName) +
+        ' 期望 hash=' + String(hashCheck.expected) + ' 实际=' + String(hashCheck.actual || '(读不到)') +
+        '——建议重新下载资源包；按 PI v2.6 语义不阻断本次运行')
+    }
+  }
+  /* tasker 要在 setupAgents 之前就绪：agent 侧 context.tasker / context.tasker.controller
+   * 经 sink 反查的就是这个 tasker 与 S.ctrl——先注册、后 connect，缺一个 sink 就是
+   * "controller not found"（见 setupAgents 注释）。 */
+  const tasker = ensureTasker()
   /* agent 桥接：项目声明了 agent（PI interface 的 child_exec/child_args）就先连上——
    * custom action 注册进本次运行的 Resource；失败不阻断（非 agent 节点照跑），结果如实报告 */
   let agentInfo = null
   if (Array.isArray(args.agents) && args.agents.length) {
-    const ag = await setupAgents(res, args.agents, String(args.agentCwd || process.cwd()))
+    const ag = await setupAgents(res, args.agents, String(args.agentCwd || process.cwd()), args.agentEnv,
+      { resource: res, controller: S.ctrl, tasker })
     agentInfo = ag.ok
-      ? { ok: true, reused: !!ag.reused, actions: ag.actions ?? null, recognitions: ag.recos ?? null }
+      ? { ok: true, reused: !!ag.reused, actions: ag.actions ?? null, recognitions: ag.recos ?? null,
+          ...(ag.sinks ? { sinks: ag.sinks } : {}) }
       : { ok: false, error: ag.error }
   }
-  const tasker = ensureTasker()
   tasker.resource = res
   tasker.controller = S.ctrl
+  /* 顺序是硬约束：先让 tasker 指向新对象，再销毁上一份。反过来（或加载失败前就销毁）会让还握着
+   * 旧句柄的 tasker 拿到已销毁的资源。buildResource 抛错时上一份原样留着。 */
+  adoptRunResource(res)
   /* timeoutMs=0：不自动 post_stop，停止权交调用方（LLM 看事件流自行判断 + run_stop）。
    * >0 时沿用超时保护（防 JumpBack 死循环）。300s 硬上限已移除——长任务用 0。 */
   const rawT = Number(args.timeoutMs)
   const timeoutMs = rawT === 0 ? 0 : (Number.isFinite(rawT) && rawT > 0 ? Math.max(500, rawT) : 30000)
   const t0 = Date.now()
   const retention = { start: await captureNow('run-start') }
-  const nodes = new Map()   // node_id → {name, start, end, msg, success, seq}
+  const nodes = new Map()   // node_id → {name, start, end, msg, success, seq, reco?, action?, frameSeq?}
   const order = []
+  let lastNodeHash = null   // 按节点留帧的去重基准：上一张已留节点帧的 blockHash（新屏才留）
   const nextCandidates = []   // 框架本轮宣布过的候选（NextList 通知），按顺序
   let nextCandidateCount = 0  // 全部公告次数（含超出上限未记入数组的）
   const onMsg = (m) => {
@@ -1152,10 +1627,26 @@ async function cmdRun(args) {
         n.name = named.name
         n.nameSource = 'node_details'
       }
-      /* node-ok/fail 锚点：读控制器缓存图（不发新截图任务，规避并发崩溃，见 anchorFromCache） */
+      /* 识别框/动作框：同一条通知里若带 details 就并入记录——后者覆盖前者，留下的是
+       * 节点结束前最后一份（通常是 Succeeded 那次的判定结果）。 */
+      const rec = pickRecoBox(m)
+      if (rec) n.reco = rec
+      const act = pickActionBox(m)
+      if (act) n.action = act
+      /* node-ok/fail 锚点：读控制器缓存图（不发新截图任务，规避并发崩溃，见 anchorFromCacheDedup）；
+       * 按节点留帧带去重——与上一张已留帧相同就跳过（画面没变重复留只是浪费锚区与字节），
+       * 并把留下的 seq 记进节点（record.nodes[].frameSeq），消费方知道"这一节点留的是哪帧"。 */
       if (/Starting$/.test(m.msg)) { n.status = 'running'; n.start = t }
-      else if (/Succeeded$/.test(m.msg)) { n.status = 'ok'; n.end = t; anchorFromCache('node-ok') }
-      else if (/Failed$/.test(m.msg)) { n.status = 'fail'; n.end = t; anchorFromCache('node-fail') }
+      else if (/Succeeded$/.test(m.msg)) {
+        n.status = 'ok'; n.end = t
+        const r = anchorFromCacheDedup('node-ok', lastNodeHash)
+        if (r.seq !== null) { n.frameSeq = r.seq; lastNodeHash = r.hash }
+      }
+      else if (/Failed$/.test(m.msg)) {
+        n.status = 'fail'; n.end = t
+        const r = anchorFromCacheDedup('node-fail', lastNodeHash)
+        if (r.seq !== null) { n.frameSeq = r.seq; lastNodeHash = r.hash }
+      }
       else if (n.msgs.length < 6) n.msgs.push(m.msg)
       n.seq = seq
       /* 节点级消息进事件流：maa_frame_poll / maa_timing_measure 直接消费 */
@@ -1197,6 +1688,10 @@ async function cmdRun(args) {
   const s2 = tasker.add_context_sink((_, m) => onMsg(m))
   S.runActive = true
   let status = null
+  /* stopped 要覆盖两条停止路径：超时保护自停（timeoutMs 分支）与 run_stop 他停。
+   * 后者靠 S.runStopped 旗标——cmdRunStop 先置旗再 post_stop，job.wait 解除后
+   * 这条旗标已经立下；没有它，"run_stop 停的"在回执里会读成"失败"。 */
+  S.runStopped = false
   let stopped = false
   try {
     const job = tasker.post_task(String(args.entry), args.override || {})
@@ -1216,6 +1711,8 @@ async function cmdRun(args) {
     } else {
       await job.wait()
     }
+    /* run_stop 走并发命令置的旗标：wait 正常解除但其实是"被要求停的" */
+    stopped = stopped || S.runStopped === true
     status = job.status
   } catch (e) {
     status = -1
@@ -1232,23 +1729,41 @@ async function cmdRun(args) {
     entry: String(args.entry),
     status,
     stopped,
+    /* 本次实际生效的超时预算：回执要能自证"是不是跑满窗口被截断"。
+     * 缺了它，`status:0 + stopped:true` 只能靠人回忆当初给的 --timeout 才分得清
+     * 「跑满窗口」与「自己结束但没成功」——两者都是 stopped:true，而处置完全不同。 */
+    timeoutMs,
     durationMs: Date.now() - t0,
+    /* baseline 落账：节点坐标/识别框所在控制器空间的短边（契约 demo-trace §meta：
+     * trace 元信息必带 baseline，跨项目迁移时与计划不一致即拒）。取控制器实际交付帧
+     * 的短边——改了 shortSide / 换过设备时如实反映，不冒称"配置值"。 */
+    baseline: Math.min(S.fullW, S.fullH) || null,
+    space: S.fullW ? { w: S.fullW, h: S.fullH } : null,
     startSeq: nodes.size ? order[0].seq : null,
     endSeq: S.seq,
     framesCaptured: S.seq,
     retention,
     ...(agentInfo ? { agent: agentInfo } : {}),
+    ...(hashCheck ? { hashCheck } : {}),
     ...(nextCandidateCount ? { nextCandidates, nextCandidateCount } : {}),
     nodes: order.map((n) => ({
       id: n.id, name: n.name, nameSource: n.nameSource, status: n.status,
       ms: (n.end ?? Date.now()) - n.start, seq: n.seq, msgs: n.msgs.slice(-6),
+      /* 识别框/动作框/节点留存帧：只增不改（协议约定），消费方按"有就读、没有就当该节点没报"处理 */
+      ...(n.reco ? { reco: n.reco } : {}),
+      ...(n.action ? { action: n.action } : {}),
+      /* 按节点留帧的 seq：画面与上一节点相同会跳过（不重复占锚区），此时没有 frameSeq */
+      ...(n.frameSeq !== undefined ? { frameSeq: n.frameSeq } : {}),
     })),
     dump: dump ? { taskCount: dump.tasks ? dump.tasks.length : 0, nodes: Object.keys(dump.nodes || {}).length } : null,
   }
-  return { ok: true, record: rec }
+  return { ok: true, record: rec, ...(runWarns.length ? { warns: runWarns } : {}) }
 }
 
 async function cmdRunStop() {
+  /* 先立旗标再 post_stop：cmdRun 的 job.wait 解除后靠它把 record.stopped 补上，
+   * 否则"run_stop 停的"会混进"任务失败"。 */
+  S.runStopped = true
   if (S.tasker) {
     try { S.tasker.post_stop() } catch (e) { /* ignore */ }
   }
@@ -1259,13 +1774,43 @@ async function cmdRunStop() {
 /* 输入注入：全部经 maafw 控制器（adb/win32 由 maafw 本体选择注入方法），不直接调 adb。
  * 动作边界（前/后）各抓一张原图进 L0 锚区（契约 §1"采得到"）：
  * 采集失败不阻断动作——动作结果与留存失败分别报告（契约 §9）。 */
+/** 帧身份守卫（纯函数，供单测）：核对"现在这帧"与调用方期望的身份。
+ * now = S.ring 最新帧（{seq, hash}）；expectSeq 是单调帧号、expectFrame 是 64bit hash 串。
+ * 返回 { ok:true } 放行；{ ok:false, error, detail } 拒发（detail 带 expected/actual 进回执）。 */
+function checkExpect(now, expectSeqRaw, expectFrameRaw) {
+  const expectSeq = expectSeqRaw !== undefined && expectSeqRaw !== null ? Number(expectSeqRaw) : null
+  const expectFrame = typeof expectFrameRaw === 'string' && expectFrameRaw ? expectFrameRaw : null
+  if (expectSeq === null && expectFrame === null) return { ok: true }
+  if (!now) return { ok: false, error: '帧身份守卫：取不到当前帧（环形缓冲空），不发输入', detail: {} }
+  if (expectSeq !== null && now.seq !== expectSeq) {
+    return { ok: false, error: '帧身份守卫不通过：期望 seq=' + expectSeq + '，当前 seq=' + now.seq
+      + '——画面已经变了（' + (now.seq - expectSeq) + ' 帧），不发输入。重看再点。',
+      detail: { expected: { seq: expectSeq }, actual: { seq: now.seq } } }
+  }
+  if (expectFrame !== null) {
+    const nowHash = hashStr(now.hash)
+    if (nowHash !== expectFrame) {
+      return { ok: false, error: '帧身份守卫不通过：期望帧 hash 与当前帧不符（期望 ' + expectFrame.slice(0, 20)
+        + '… 当前 ' + nowHash.slice(0, 20) + '…，seq=' + now.seq + '）——画面已经变了，不发输入。',
+        detail: { expected: { frameHash: expectFrame }, actual: { seq: now.seq, frameHash: nowHash } } }
+    }
+  }
+  return { ok: true }
+}
+
 async function cmdInput(args) {
   if (!S.ctrl) return { ok: false, error: '未连接设备（先 maa_connect）' }
   const t0 = Date.now()
   const k = String(args.kind || 'click')
   const retention = {}
   const done = (job) => ({ ok: true, kind: k, ms: Date.now() - t0, retention })
-  retention.before = await captureNow('action-before')
+  retention.before = await captureNow('action-before', true)
+  /* 帧身份守卫：调用方说"我是在看到 seq=N 那帧之后决定要点的"——守卫核对**现在**这帧
+   * 是不是同一帧。不是就不发输入（MPE validateClick 的拒点同义：画面已经变了，按旧画面
+   * 算的坐标点下去就是误触）。seq 是单调计数器、expectFrame 是像素 hash——前者快（同 seq
+   * 必同像素），后者跨 seq 也能核（同一画面重现）。回执里 code 让 CLI 落到 FINDINGS(3)。 */
+  const chk = checkExpect(S.ring[S.ring.length - 1], args.expectSeq, args.expectFrame)
+  if (!chk.ok) return { ok: false, code: 'EXPECT_FAILED', kind: k, error: chk.error, retention, ...chk.detail }
   let job = null
   if (k === 'click') {
     job = S.ctrl.post_click(Number(args.x), Number(args.y), Number(args.contact ?? 0), Number(args.pressure ?? 1))
@@ -1312,7 +1857,7 @@ async function cmdInput(args) {
       /* 与共享尾同一口径：**先 wait 再抓 after**。抓早了可能截在抬手落地之前，
        * 而手势类动作恰恰要验证"抬手之后画面变成什么样"。 */
       await job.wait()
-      retention.after = await captureNow('action-after')
+      retention.after = await captureNow('action-after', true)
       return { ...done(null), path: pts, viaCount: via.length, stepMs: step }
     }
     job = S.ctrl.post_swipe(Number(args.x1), Number(args.y1), Number(args.x2), Number(args.y2),
@@ -1323,7 +1868,7 @@ async function cmdInput(args) {
     const contact = Number(args.contact ?? 0)
     job = S.ctrl.post_touch_move(contact, Number(args.x), Number(args.y), Number(args.pressure ?? 1))
     await job.wait()
-    retention.after = await captureNow('action-after')
+    retention.after = await captureNow('action-after', true)
     return done(null)
   } else if (k === 'touch_down' || k === 'touch_up') {
     const contact = Number(args.contact ?? 0)
@@ -1331,7 +1876,7 @@ async function cmdInput(args) {
       ? S.ctrl.post_touch_down(contact, Number(args.x), Number(args.y), Number(args.pressure ?? 1))
       : S.ctrl.post_touch_up(contact)
     await job.wait()
-    retention.after = await captureNow('action-after')
+    retention.after = await captureNow('action-after', true)
     return done(null)
   } else if (k === 'key') {
     job = S.ctrl.post_click_key(Number(args.code))
@@ -1344,7 +1889,7 @@ async function cmdInput(args) {
     for (const c of codes) await S.ctrl.post_key_down(c).wait()
     await sleep(hold)
     for (const c of codes.slice().reverse()) await S.ctrl.post_key_up(c).wait()
-    retention.after = await captureNow('action-after')
+    retention.after = await captureNow('action-after', true)
     return done(null)
   } else if (k === 'scroll') {
     /* 滚轮：dx/dy 为格数，建议 120 的倍数（WHEEL_DELTA） */
@@ -1362,10 +1907,19 @@ async function cmdInput(args) {
     return { ok: false, error: 'unknown input kind: ' + k + '（click|dbclick|press|swipe|key|keys|scroll|move|text|app）' }
   }
   await job.wait()
-  retention.after = await captureNow('action-after')
+  retention.after = await captureNow('action-after', true)
   return done(job)
 }
 
+/**
+ * 子进程预算：用例数越多放得越宽（实测每例 ≈ 0.24s，留 5s/例的余量）。
+ * 固定 90s 会让"几十个候选"在慢机器上被误杀，而误杀的表现是"识别子进程失败"——
+ * 与真正的识别失败分不开。上限仍由 spawnRecoChild 自己封（120s）。
+ */
+function recoChildBudget(cases) {
+  return Math.max(90000, Number(cases) * 5000)
+}
+
 /* 识别单测：子进程隔离执行（beta 绑定的 post_recognition 在无效模板上会原生崩溃，
  * 子进程炸掉只损失一次测试，绝不让宿主陪葬）。 */
 function spawnRecoChild(payload, timeoutMs) {
@@ -1406,12 +1960,19 @@ function stripDetail(d) {
  * 专测 target 框语义（框中心/偏移）与组合动作。识别输入 = 抓帧时的当前画面原图
  * （也是 action-before 边界锚点），动作执行后的画面另抓 action-after——效果可复核。
  */
-async function recoActTest(args, node) {
-  const res = await ensureResource(String(args.resourceDir))
+async function recoActTest(args, node, dirs) {
+  /* 有任务在飞时不换资源：act 会改写 tasker.resource，等于把正在跑的任务的资源换掉。
+   * 这条路径本来也不该在 run 期间用（要真机动作就等任务结束）。 */
+  if (S.runActive) return { ok: false, error: '有任务正在运行：先 maa_run_stop 再跑 --act（改资源会打断在跑的任务）' }
+  /* 资源链与识别路径同一份：节点里的模板/被引用子节点可能只在 overlay 段里。
+   * 同样每次新建，不与会话里任何资源共享（act 会注册/注销 custom action，复用更不可取）。 */
+  const res = await buildResource(dirs)
   const tasker = ensureTasker()
   tasker.resource = res
   tasker.controller = S.ctrl
-  const before = await captureNow('action-before')
+  /* 先让 tasker 指向新对象，再销毁上一份（见 adoptRunResource 的调用前提） */
+  adoptRunResource(res)
+  const before = await captureNow('action-before', true)
   if (!before.ok) return { ok: false, error: '识别输入抓帧失败：' + before.error }
   const imgBuf = S.l0.roll[S.l0.roll.length - 1].png
   const image = imgBuf.buffer.slice(imgBuf.byteOffset, imgBuf.byteOffset + imgBuf.byteLength)
@@ -1447,13 +2008,17 @@ async function recoActTest(args, node) {
   } finally {
     try { res.unregister_custom_action('@reco/act') } catch (e) { /* ignore */ }
   }
-  const after = await captureNow('action-after')
+  const after = await captureNow('action-after', true)
   if (!out) return { ok: false, error: '动作探针未被执行（custom action 回调未触发）' }
   const rec = node && node.recognition
   const shownType = rec && typeof rec === 'object' ? String(rec.type ?? 'DirectHit') : String(rec ?? 'DirectHit')
   return {
     ok: out.ok,
     type: shownType,
+    /* 与识别路径同一口径：这次用的是整条资源链（含 attach 段），layer=resource 表示这里没有
+     * interface 的四级 pipeline_override（run --project 才会叠） */
+    resource: { dirs },
+    layer: 'resource',
     meta: { seq: before.seq, w: before.w, h: before.h, t: before.t },
     ...(out.error !== undefined ? { error: out.error } : {}),
     ...(out.stage ? { stage: out.stage } : {}),
@@ -1465,14 +2030,27 @@ async function recoActTest(args, node) {
 }
 
 async function cmdRecoTest(args) {
+  /* 资源链：resourceDirs[] 是 interface.json 的 resource.path[]（+ 控制器 attach_resource_path）
+   * 按声明顺序叠加的结果；resourceDir 是单包写法。只有单包时测的就不是项目里那个节点——
+   * overlay 段的节点改写、只存在于 overlay 的模板、被 And/Or 按名引用的子节点全会缺。 */
+  const chain = Array.isArray(args.resourceDirs) ? args.resourceDirs.map((d) => String(d)).filter((d) => d) : []
+  const dirs = chain.length ? chain : (args.resourceDir ? [String(args.resourceDir)] : [])
+  if (!dirs.length) return { ok: false, error: '缺少资源：给 resourceDirs[]（整链）或 resourceDir（单包）' }
+  const nodeName = typeof args.nodeName === 'string' && args.nodeName !== '' ? args.nodeName : null
+  if (nodeName && args.node && typeof args.node === 'object' && !Array.isArray(args.node)) {
+    return { ok: false, error: 'node 与 nodeName 互斥：一次只测一个节点来源' }
+  }
   /* --act：节点级单测（识别拿框 → 真机执行动作半），在 daemon 进程内跑（要真控制器） */
   const actNode = args.act === true && args.node && typeof args.node === 'object' && !Array.isArray(args.node) ? args.node : null
   if (args.act === true) {
+    if (nodeName) return { ok: false, error: '--act 不接受 nodeName：按资源原名跑的是识别判据，动作半要真机桥接（那是 run）' }
     if (!actNode) return { ok: false, error: '--act 需要同时给 --node（整节点 JSON，含 action）' }
     if (!S.ctrl) return { ok: false, error: '--act 要在真机上执行动作：需要已连接设备（REPL 或 --project/--kind）' }
-    return await recoActTest(args, actNode)
+    return await recoActTest(args, actNode, dirs)
   }
-  await ensureResource(args.resourceDir)   // 校验资源可加载（子进程会重新加载）
+  /* 资源链可加载性先验已挪进 reco_child（同一次加载里逐段点名失败段）：原先这里
+   * probeResourceChain 先加载一遍、子进程再加载一遍，识别一慢就是双倍预算，
+   * 且永远是客户端先到点杀进程（设计审查 P0-1）。 */
   /* 图像来源三条：库内留存帧（kfSource：控制器分辨率原图、**可无设备**）/ 显式文件 / 会话缓冲帧。
    * daemon 自己写的那份临时 PNG **用完即删**——不删就是每跑一次漏一个（CLI 侧的截帧泄漏是同一类，
    * 现场实测攒过 42 张；这条 `--seq` 路径同理，只是本机还没被触发过）。 */
@@ -1488,7 +2066,10 @@ async function cmdRecoTest(args) {
     meta = { source: kf.source.id, sha256: kf.source.sha256, w: kf.dec.w, h: kf.dec.h, ctrlW: kf.dec.w, ctrlH: kf.dec.h }
   } else if (args.image) {
     imageFile = String(args.image)
-    meta = { source: args.image }
+    /* 补 w/h：没有它，调用方无法判断 roi 用的是哪个空间（信息补齐，不改取图行为） */
+    let size = null
+    try { size = pngHeaderSize(fs.readFileSync(imageFile)) } catch (e) { /* 读不到留给子进程报错 */ }
+    meta = { source: args.image, ...(size ? { w: size.w, h: size.h } : {}) }
   } else {
     const fr = args.seq !== undefined && args.seq !== null
       ? S.ring.find((r) => r.seq === Number(args.seq))
@@ -1507,8 +2088,32 @@ async function cmdRecoTest(args) {
   }
   const baseParam = args.param && typeof args.param === 'object' ? args.param : {}
   const sweep = args.sweep && typeof args.sweep === 'object' ? args.sweep : null
+  /* --candidates：候选集合逐例换 roi（roi-compare 走的正是这条）。
+   * 与 sweep 像但**不变量不同**：sweep 是"同键换值"，候选是"逐例换 roi"——
+   * 折叠进同一个 cases、走同一次 spawnRecoChild，不新开第二条子进程通道。 */
+  const candidates = Array.isArray(args.candidates) ? args.candidates : null
+  if (candidates && sweep && typeof sweep.min === 'number') {
+    return { ok: false, error: 'candidates 与 sweep 互斥：一次识别单测只跑一种候选来源' }
+  }
+  if (candidates && !candidates.length) {
+    return { ok: false, error: 'candidates 是空数组：至少给一个 [x,y,w,h] 候选' }
+  }
+  /* node / nodeName 与候选来源互斥：整条节点路径（dump + 节点自己的 recognition/param）
+   * 已经是一次完整的"跑这个节点"，cases 根本没有位置塞——同给会静默丢掉候选集合，
+   * 调用方还以为 roi-compare 的逐例换 roi 生效了（P1-#5 协议面）。 */
+  if ((node || nodeName) && (candidates || (sweep && typeof sweep.min === 'number'))) {
+    return { ok: false, error: 'node/nodeName 与 candidates/sweep 互斥：整条节点路径有自己完整的 param，没有逐例换值的位置' }
+  }
   const cases = []
-  if (sweep && typeof sweep.min === 'number' && typeof sweep.max === 'number') {
+  if (candidates) {
+    for (const c of candidates) {
+      const roi = Array.isArray(c) ? c.map(Number) : null
+      if (!roi || roi.length !== 4 || !roi.every(Number.isFinite)) {
+        return { ok: false, error: 'candidates 每项都要是 [x,y,w,h] 四个数字，收到：' + JSON.stringify(c) }
+      }
+      cases.push({ ...baseParam, roi })
+    }
+  } else if (sweep && typeof sweep.min === 'number' && typeof sweep.max === 'number') {
     /* step 带方向：升序 0.5→0.9 / 降序 0.9→0.5 都合法；区间为空明确报错，不静默测个空 */
     const step = sweep.step !== undefined && Number(sweep.step) !== 0 ? Number(sweep.step) : 1
     const up = step > 0
@@ -1522,25 +2127,43 @@ async function cmdRecoTest(args) {
   let r = null
   try {
     r = await spawnRecoChild({
-      resourceDir: String(args.resourceDir),
+      ...(chain.length ? { resourceDirs: dirs } : { resourceDir: dirs[0] }),
       type: String(args.type || 'TemplateMatch'),
       image: imageFile,
       /* 面板场景：模板由调用方裁好落盘传进来（子进程走 override_image），不写进任何资源目录 */
       ...(args.templateImage ? { templateImage: String(args.templateImage) } : {}),
-      ...(node ? { node } : { cases }),
-    }, 90000)
+      ...(node ? { node } : (nodeName ? { nodeName } : { cases })),
+    }, recoChildBudget(cases.length))
   } finally {
     /* 子进程已经读完这张图（spawnRecoChild 会等到它退出），此时删除是安全的 */
     if (tempImage) { try { fs.rmSync(tempImage, { force: true }) } catch (e) { /* ignore */ } }
   }
+  /* 回执带资源链与层级：layer=resource 表示这里只到"资源合并结果"，
+   * run --project 还会再叠 interface 的四级 pipeline_override（GUI 选项改过同一字段时两者对不上是预期） */
+  const resource = { dirs }
   if (r && r.ok) {
     const rec = node && node.recognition
     const shownType = node
       ? (rec && typeof rec === 'object' ? String(rec.type ?? 'DirectHit') : String(rec))
-      : args.type
-    return { ok: true, type: shownType, meta, results: r.results }
+      : String(r.type ?? args.type ?? 'TemplateMatch')
+    return {
+      ok: true, type: shownType, meta, results: r.results, resource, layer: 'resource',
+      ...(nodeName ? { nodeName } : {}),
+      ...(r.nodeDump ? { nodeDump: r.nodeDump } : {}),
+    }
+  }
+  return {
+    ok: false,
+    error: (r && r.error) || 'reco 失败',
+    meta, resource, layer: 'resource',
+    ...(r && r.code ? { code: String(r.code) } : {}),
+    /* 近邻节点名：`--node-name` 拼错时给出"是不是想跑这个"，CLI/REPL 直接把它变成 hint */
+    ...(r && Array.isArray(r.candidates) && r.candidates.length ? { candidates: r.candidates.map(String) } : {}),
+    /* 嵌套 custom 的命中位置：让人知道是节点自己，还是 And/Or 里的子识别 */
+    ...(r && Array.isArray(r.customPaths) && r.customPaths.length ? { customPaths: r.customPaths.map(String) } : {}),
+    ...(nodeName ? { nodeName } : {}),
+    ...(r && r.nodeDump ? { nodeDump: r.nodeDump } : {}),
   }
-  return { ok: false, error: (r && r.error) || 'reco 失败', meta }
 }
 
 /* ────────────────────────── 关键帧库（L0 升格 + 登记，契约 §4） ──────────────────────────
@@ -1572,6 +2195,44 @@ function kfSave(m) {
   fs.renameSync(tmp, file)
 }
 
+/* ─── 关键帧库写锁（P1-#8）───────────────────────────────────────────────────
+ * manifest 的读-改-写此前无锁：常驻会话与一次性 `crop --keep-source` 同秒升格时，
+ * 两个进程都读 m.next=N、都写 l0/000N.png，manifest 后写者赢——已发出的 kf ID
+ * 指向另一份像素或 sha 校验失败。锁是文件系统可见的（跨 daemon 进程）；
+ * O_EXCL 拿锁（原子，不会两人同时创建成功）；持有者崩了留残渣时按 mtime 过期重拿。 */
+const KF_LOCK_STALE_MS = 60_000
+function kfLockPath() { return path.join(kfRoot(), 'manifest.lock') }
+function kfLockAcquire() {
+  const p = kfLockPath()
+  fs.mkdirSync(kfRoot(), { recursive: true })
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    try {
+      const fd = fs.openSync(p, 'wx')   /* 'wx' = O_EXCL：存在即抛，原子拿锁 */
+      fs.closeSync(fd)
+      return true
+    } catch (e) {
+      if (e.code !== 'EEXIST') return false
+      /* 锁在：看是不是崩溃残渣（mtime 太老 = 持有者死了没放） */
+      try {
+        const age = Date.now() - fs.statSync(p).mtimeMs
+        if (age > KF_LOCK_STALE_MS) {
+          try { fs.rmSync(p, { force: true }) } catch (e2) { /* ignore */ }
+          continue   /* 删掉残渣立即重试拿锁 */
+        }
+      } catch (e2) { /* stat 失败当新锁等 */ }
+      /* 新锁：等持有者放。帧库写者并发本来就极低（常驻 + 一次性偶发），
+       * 单次升格毫秒级——40ms 空转一拍就够。 */
+      const t0 = Date.now()
+      while (Date.now() - t0 < 40) { /* spin */ }
+    }
+  }
+  return false
+}
+function kfLockRelease() {
+  try { fs.rmSync(kfLockPath(), { force: true }) } catch (e) { /* ignore */ }
+}
+
 /** 库目录现有 L0 字节（按 manifest 记录的文件实测；丢失文件计 0——磁盘占用只算真实存在的） */
 function kfUsageBytes(m) {
   let total = 0
@@ -1581,85 +2242,113 @@ function kfUsageBytes(m) {
   return total
 }
 
-async function cmdKfPromote(args) {
-  /* 固定捕获身份：latest 在接受请求时解析成具体 seq；已淘汰则失败，绝不改取更新帧冒充 */
-  let seq = null
-  if (args.seq !== undefined && args.seq !== null) {
-    seq = Number(args.seq)
-    if (!Number.isFinite(seq)) return { ok: false, error: 'seq 必须是数字' }
-  } else if (args.latest === true) {
-    seq = S.seq
-  } else {
-    return { ok: false, error: '给 seq（数字）或 latest:true 指定要升格的捕获' }
-  }
-  if (seq <= 0) return { ok: false, error: '本会话尚无捕获（seq=0），无可升格' }
+async function cmdKfPromoteOne(seq, note) {
+  /* 单个 seq 升格（供 cmdKfPromote 与批量模式共用）。返回 { ok, id?, error?, ... } */
+  if (seq <= 0) return { ok: false, error: '本会话尚无捕获（seq=0），无可升格', seq }
   const ent = S.l0.anchor.find((x) => x.seq === seq) ?? S.l0.roll.find((x) => x.seq === seq)
   if (!ent) {
     const range = (l) => (l.length ? l[0].seq + '..' + l[l.length - 1].seq : '空')
     return {
-      ok: false,
+      ok: false, seq,
       error: 'L0 已淘汰：seq=' + seq + '（滚动区 ' + range(S.l0.roll) + '，锚区 ' + range(S.l0.anchor) + '）。' +
-        'L1 参考帧可用 frame_get 导出，但按契约不作 state 证据本体',
+        '可降级导出参考帧：frame_get ' + seq + ' --out <file>（L1 参考帧，按契约不作 state 证据本体）',
     }
   }
+  /* manifest 读-改-写外面加文件锁（P1-#8）：常驻会话与一次性 crop --keep-source
+   * 同秒升格时，两个进程不能各读各的 m.next=N、各写各的 l0/000N.png 后让 manifest
+   * 后写者赢——那会让一个已发出的 kf ID 指向另一份像素。拿锁后重读 manifest，
+   * 整个 RMW 都在临界区。 */
+  if (!kfLockAcquire()) {
+    return { ok: false, seq, error: '关键帧库写锁拿不到（30s）：另一进程可能在升格/崩溃残留——稍候重试，或查 ' + kfLockPath() }
+  }
   let m
-  try { m = kfOpen() } catch (e) { return { ok: false, error: '关键帧库不可用：' + String(e && e.message || e) } }
+  try { m = kfOpen() } catch (e) { kfLockRelease(); return { ok: false, error: '关键帧库不可用：' + String(e && e.message || e), seq } }
   const sess = S.session || {}
   const sessionRef = { daemon: S.daemonId, gen: S.connGen, kind: sess.kind ?? null, target: sess.target ?? null }
   const sha = createHash('sha256').update(ent.png).digest('hex')
-  /* 幂等：同一捕获（daemon + 代次 + seq）重试返回原对象；内容不符报冲突，不任选一份 */
-  const dup = m.frames.find((f) => f.session && f.session.daemon === sessionRef.daemon &&
-    Number(f.session.gen) === sessionRef.gen && Number(f.captureSeq) === seq)
-  if (dup) {
-    if (dup.sha256 === sha) return { ok: true, idempotent: true, id: dup.id, record: dup, path: kfAbsPath(dup.file), sha256: sha }
-    return { ok: false, error: '同一捕获已有内容不同的记录（' + dup.id + '）：冲突，拒绝改写旧 ID 的含义' }
-  }
-  /* 磁盘配额（契约 §4.1）：幂等重试在上面已返回，走到这里的都是新增字节。
-   * 满额拒绝并报告——已升格对象不后台清理，清理由用户决定。 */
-  if (S.kfQuota > 0) {
-    const used = kfUsageBytes(m)
-    const mb = (v) => (v / 1048576).toFixed(1) + 'MB'
-    if (used + ent.png.length > S.kfQuota) {
-      return {
-        ok: false,
-        error: '关键帧库配额不足：已用 ' + mb(used) + ' + 新增 ' + mb(ent.png.length) +
-          ' 超过配额 ' + mb(S.kfQuota) + '（' + m.frames.length + ' 帧留存于 ' + kfRoot() + '）。' +
-          '不会自动删除已升格帧——清理后重试，或调大配额（init kfQuotaBytes / MAAFW_KF_QUOTA_BYTES）',
+  try {
+    /* 幂等：同一捕获（daemon + 代次 + seq）重试返回原对象；内容不符报冲突，不任选一份 */
+    const dup = m.frames.find((f) => f.session && f.session.daemon === sessionRef.daemon &&
+      Number(f.session.gen) === sessionRef.gen && Number(f.captureSeq) === seq)
+    if (dup) {
+      if (dup.sha256 === sha) return { ok: true, idempotent: true, id: dup.id, record: dup, path: kfAbsPath(dup.file), sha256: sha, seq }
+      return { ok: false, seq, error: '同一捕获已有内容不同的记录（' + dup.id + '）：冲突，拒绝改写旧 ID 的含义' }
+    }
+    /* 磁盘配额（契约 §4.1）：幂等重试在上面已返回，走到这里的都是新增字节。
+     * 满额拒绝并报告——已升格对象不后台清理，清理由用户决定。 */
+    if (S.kfQuota > 0) {
+      const used = kfUsageBytes(m)
+      const mb = (v) => (v / 1048576).toFixed(1) + 'MB'
+      if (used + ent.png.length > S.kfQuota) {
+        return {
+          ok: false, seq,
+          error: '关键帧库配额不足：已用 ' + mb(used) + ' + 新增 ' + mb(ent.png.length) +
+            ' 超过配额 ' + mb(S.kfQuota) + '（' + m.frames.length + ' 帧留存于 ' + kfRoot() + '）。' +
+            '不会自动删除已升格帧——清理后重试，或调大配额（init kfQuotaBytes / MAAFW_KF_QUOTA_BYTES）',
+        }
       }
     }
+    const num = Number(m.next) || m.frames.length + 1
+    const id = 'kf:' + m.libraryId + ':' + String(num).padStart(4, '0')
+    const fileRel = 'l0/' + String(num).padStart(4, '0') + '.png'
+    const abs = kfAbsPath(fileRel)
+    try {
+      fs.mkdirSync(path.dirname(abs), { recursive: true })
+      const tmp = abs + '.tmp'
+      fs.writeFileSync(tmp, ent.png)
+      fs.renameSync(tmp, abs)
+    } catch (e) {
+      return { ok: false, seq, error: 'L0 文件写入失败：' + String(e && e.message || e) }
+    }
+    /* 小图信息只取环内同 seq 帧；已淘汰则明确为空，不借用最新帧数据（契约 §4） */
+    const small = S.ring.find((r) => r.seq === seq)
+    const rec = {
+      id, file: fileRel, sha256: sha,
+      session: sessionRef,
+      capturedAt: new Date(ent.t).toISOString(),
+      captureSeq: seq,
+      ctrlW: ent.w, ctrlH: ent.h,
+      smallW: small ? small.w : null, smallH: small ? small.h : null,
+      scale: small && ent.w ? Math.round((small.w / ent.w) * 1000) / 1000 : null,
+      source: ent.source || 'explicit',
+      note: note != null ? String(note) : null,
+    }
+    m.frames.push(rec)
+    m.next = num + 1
+    try { kfSave(m) } catch (e) {
+      try { fs.rmSync(abs, { force: true }) } catch (e2) { /* ignore */ }
+      return { ok: false, seq, error: 'manifest 写入失败（L0 文件已回收，未发布引用）：' + String(e && e.message || e) }
+    }
+    return { ok: true, id, path: abs, sha256: sha, retained: 'promoted', record: rec, seq }
+  } finally {
+    kfLockRelease()
   }
-  const num = Number(m.next) || m.frames.length + 1
-  const id = 'kf:' + m.libraryId + ':' + String(num).padStart(4, '0')
-  const fileRel = 'l0/' + String(num).padStart(4, '0') + '.png'
-  const abs = kfAbsPath(fileRel)
-  try {
-    fs.mkdirSync(path.dirname(abs), { recursive: true })
-    const tmp = abs + '.tmp'
-    fs.writeFileSync(tmp, ent.png)
-    fs.renameSync(tmp, abs)
-  } catch (e) {
-    return { ok: false, error: 'L0 文件写入失败：' + String(e && e.message || e) }
-  }
-  /* 小图信息只取环内同 seq 帧；已淘汰则明确为空，不借用最新帧数据（契约 §4） */
-  const small = S.ring.find((r) => r.seq === seq)
-  const rec = {
-    id, file: fileRel, sha256: sha,
-    session: sessionRef,
-    capturedAt: new Date(ent.t).toISOString(),
-    captureSeq: seq,
-    ctrlW: ent.w, ctrlH: ent.h,
-    smallW: small ? small.w : null, smallH: small ? small.h : null,
-    scale: small && ent.w ? Math.round((small.w / ent.w) * 1000) / 1000 : null,
-    source: ent.source || 'explicit',
-    note: args.note != null ? String(args.note) : null,
+}
+
+async function cmdKfPromote(args) {
+  /* 批量：args.seqs 为 seq 数组（CLI 的 "3909 3910" 或 "a..b" 已解析好）。
+   * 逐条走 cmdKfPromoteOne，各自的成功/淘汰分开报告，不因一条失败中断整批。 */
+  if (Array.isArray(args.seqs) && args.seqs.length > 0) {
+    const results = []
+    for (const s of args.seqs) {
+      results.push(await cmdKfPromoteOne(Number(s), args.note))
+    }
+    const ok = results.every((r) => r.ok)
+    const promoted = results.filter((r) => r.ok)
+    const failed = results.filter((r) => !r.ok)
+    return { ok, results, promoted: promoted.length, failed: failed.length }
   }
-  m.frames.push(rec)
-  m.next = num + 1
-  try { kfSave(m) } catch (e) {
-    try { fs.rmSync(abs, { force: true }) } catch (e2) { /* ignore */ }
-    return { ok: false, error: 'manifest 写入失败（L0 文件已回收，未发布引用）：' + String(e && e.message || e) }
+  /* 固定捕获身份：latest 在接受请求时解析成具体 seq；已淘汰则失败，绝不改取更新帧冒充 */
+  let seq = null
+  if (args.seq !== undefined && args.seq !== null) {
+    seq = Number(args.seq)
+    if (!Number.isFinite(seq)) return { ok: false, error: 'seq 必须是数字' }
+  } else if (args.latest === true) {
+    seq = S.seq
+  } else {
+    return { ok: false, error: '给 seq（数字）、latest:true，或 seqs 数组（批量）指定要升格的捕获' }
   }
-  return { ok: true, id, path: abs, sha256: sha, retained: 'promoted', record: rec }
+  return cmdKfPromoteOne(seq, args.note)
 }
 
 function cmdL0Status() {
@@ -1863,20 +2552,39 @@ function buildL2Provenance(o) {
     level: 'L2',
     derivedFrom,
     transform: { op: 'crop', resize: false, scale: 1, loose: o.loose, crop: o.box, snapped: o.snapped },
-    selfMatch: { score: o.score, positionOk: o.positionOk, box: o.selfMatchBox ?? null, tries: o.tries },
+    /* annotate --emit-crops 裁的是 SoM 候选，不走自匹配验证——selfMatch 如实为 null，
+     * 不伪造"没测过的匹配度"（契约 §5 的变换与来源照样全）。 */
+    selfMatch: o.selfMatch === null ? null : { score: o.score, positionOk: o.positionOk, box: o.selfMatchBox ?? null, tries: o.tries },
     cross: o.cross ?? null,
     output: { w: o.w, h: o.h },
     createdAt: o.createdAt,
-    tool: 'maafw-live crop',
+    tool: o.tool ?? 'maafw-live crop',
   }
 }
 
-/** 缺省落点：daemon 的 run 目录下 `out/`（一次性命令给的是临时目录）——**不写调用方的 cwd**。
- * 调用方的 cwd 通常就是项目仓库：一次 `frame_get` / `annotate` 就把产物丢进仓库。
+/** 缺省落点 out/ 的保留上限（只进不出的产物，不让它无声膨胀） */
+const OUT_KEEP = 50
+/** out/ 目录保留修剪：按 mtime 留最新 OUT_KEEP 个 .png。与 client 侧 src/runtime/prune.ts 同逻辑的内联
+ *  副本——framed.mjs 自包含、不能 import lib。失败不抛：清理从来不是任务结论。 */
+function pruneOutDir(dir) {
+  try {
+    const names = fs.readdirSync(dir)
+      .filter((n) => n.endsWith('.png'))
+      .map((n) => ({ n, t: fs.statSync(path.join(dir, n)).mtimeMs }))
+      .sort((a, b) => b.t - a.t)
+    for (const f of names.slice(OUT_KEEP)) {
+      try { fs.unlinkSync(path.join(dir, f.n)) } catch { /* 单个删不掉就留 */ }
+    }
+  } catch { /* 目录不存在/读不了：没有要清的 */ }
+}
+
+/** 缺省落点：daemon 的 run 目录下 `out/`（缺省 runDir 是 `~/.maafw-live`，不是临时目录）——
+ * **不写调用方的 cwd**。调用方的 cwd 通常就是项目仓库：一次 `frame_get` / `annotate` 就把产物丢进仓库。
  * 实测踩过两次（`maa_frame_*.png` 十张进了 maafw-live 仓、`maa_som_*.png` 进了同一个根目录），
  * 而这几个命令本质是"看/量"，产物只是顺便落盘——落哪儿由 `out` 说话，不落调用方家里。 */
 function defaultOutFile(runDir, prefix, ts = Date.now()) {
   const dir = path.join(runDir || os.tmpdir(), 'out')
+  pruneOutDir(dir) /* 只在缺省落点修剪——显式 out 是用户指定的位置，不动它 */
   return { dir, file: path.join(dir, prefix + '-' + ts + '.png') }
 }
 
@@ -1993,12 +2701,19 @@ async function cmdTplCrop(args) {
     const r = await spawnRecoChild({
       resourceDir, type: 'TemplateMatch', image: frameFile, templateImage: candFile, cases: [{}],
     }, 60000)
-    if (!r || !r.ok) return { score: -1, posOk: false, at: null }
+    if (!r || !r.ok) {
+      /* 资源链加载不出来（reco 把这条明确报成 `RESOURCE_LOAD`）与"识别跑了但没命中"是两回事：
+       * 前者是资源问题、处置是去修资源，后者才是去换框。别让它落进"低纹理/不独特"。 */
+      if (r && (r.code === 'RESOURCE_LOAD' || /资源链加载失败/.test(String(r.error ?? '')))) {
+        selfMatchDead = selfMatchDead ?? ('资源链加载不出来——' + String(r.error ?? '').trim())
+      }
+      return { score: -1, posOk: false, at: null }
+    }
     /* 子进程回 ok 但**一个 case 结果都没有**：识别压根没跑起来（实测最常见的原因是资源目录里没有可加载的
      * pipeline，reco 会安静地回 `results: []`）。这与"识别跑了但没命中"是两回事——后者仍会有 1 条结果
      * （hit:false）。记下来，别让它被下面的判据翻译成"低纹理/不独特"。 */
     if (!Array.isArray(r.results) || r.results.length === 0) {
-      selfMatchDead = true
+      selfMatchDead = selfMatchDead ?? '识别子进程一个结果都没回'
       return { score: -1, posOk: false, at: null, noResults: true }
     }
     const det = r.results && r.results[0] ? r.results[0].detail : null
@@ -2008,8 +2723,9 @@ async function cmdTplCrop(args) {
     return { score: Number(best.score), posOk: overlapOk(at, [b.x, b.y, b.w, b.h]), at }
   }
   const obj = (s) => (s.posOk ? 1000 : 0) + s.score
-  /** 自匹配有没有跑起来（子进程回空结果 = 没跑起来）。跑到这里说明资源加载不出识别节点。 */
-  let selfMatchDead = false
+  /** 自匹配有没有跑起来：null = 跑起来了；字符串 = 没跑起来的具体原因（子进程回空结果 / 资源链加载不出来）。
+   * 跑到这里还能不跑起来，说明资源那边加载不出识别节点。 */
+  let selfMatchDead = null
   const clampBox = (b) => ({
     x: Math.max(0, b.x), y: Math.max(0, b.y),
     w: Math.min(b.w, dec.w - Math.max(0, b.x)), h: Math.min(b.h, dec.h - Math.max(0, b.y)),
@@ -2141,8 +2857,8 @@ async function cmdTplCrop(args) {
   const out = args.out || defaultOutFile(S.runDir, 'tpl').file
   fs.mkdirSync(path.dirname(out), { recursive: true })
   fs.writeFileSync(out, pngEncodeRGB(final.data, final.w, final.h))
-  const warn = selfMatchDead
-    ? '自匹配没跑起来：识别子进程一个结果都没回（实测最常见原因是资源目录里没有可加载的 pipeline）。' +
+  const warn = selfMatchDead !== null
+    ? '自匹配没跑起来：' + selfMatchDead + '（实测最常见原因是资源目录里没有可加载的 pipeline）。' +
       '这不是"模板不独特"——先写一个 pipeline 节点，或用 --resource-dir 指向真实资源，再重跑这次的框；' +
       '在此之前它**未经自匹配验证**，不要拿它去写 pipeline'
     : !best.posOk
@@ -2693,6 +3409,34 @@ async function cmdAnnotate(args) {
     drawRect(buf, draw.w, draw.h, [rb[0] + 1, rb[1] + 1, Math.max(2, rb[2] - 2), Math.max(2, rb[3] - 2)], [255, 255, 255])
   }
   fs.writeFileSync(out, pngEncodeRGB(buf, draw.w, draw.h))
+
+  /* --emit-crops <dir>：每个进表候选从 work 图（检测面：L0 全分辨率 or kf 原图 or 降级小图）
+   * 切一张 PNG + 写 .prov.json 出处。box 是 work 坐标系——k 库帧与工作图同空间，x/y 直接裁。
+   * selfMatch 为 null：这是"候选一键出模板"的批量出图，未经自匹配验证；要自匹配（选号）
+   * 走正式 crop。 */
+  const emitted = []
+  const emitDir = typeof args.emitCrops === 'string' && args.emitCrops ? String(args.emitCrops) : null
+  if (emitDir) {
+    try {
+      fs.mkdirSync(emitDir, { recursive: true })
+      cands.forEach((c, i) => {
+        const id = i + 1
+        const b = { x: Math.round(c.box[0]), y: Math.round(c.box[1]), w: Math.round(c.box[2]), h: Math.round(c.box[3]) }
+        const crop = cropRgb(work.rgb, work.w, work.h, b)
+        const f = path.join(emitDir, 'cand-' + String(id).padStart(2, '0') + '.png')
+        fs.writeFileSync(f, pngEncodeRGB(crop.data, crop.w, crop.h))
+        const prov = buildL2Provenance({
+          source, loose: b, box: [b.x, b.y, b.w, b.h], snapped: false, selfMatch: null,
+          cross: null, w: crop.w, h: crop.h, createdAt: new Date().toISOString(),
+          tool: 'maafw-live annotate --emit-crops',
+        })
+        const pf = f + '.prov.json'
+        fs.writeFileSync(pf, JSON.stringify(prov, null, 2) + '\n')
+        emitted.push({ id, path: f, provPath: pf, w: crop.w, h: crop.h, source: c.source })
+      })
+    } catch (e) { /* 逐条写失败不中断 annotate：emit 是可选增值，不是主结果 */ }
+  }
+
   const ctrlW = work.fw > 0 ? work.fw : work.w
   const ctrlH = work.fh > 0 ? work.fh : work.h
   /* 候选框的面积占比（控制器空间，与画面同尺度）：调用方可据此再排一次序——
@@ -2728,6 +3472,7 @@ async function cmdAnnotate(args) {
     ...(args.kfSource ? { sourcesUnavailable: { diff: '库帧路径无会话事件：diff 源不可用（不拿别的区域顶替）' } } : {}),
     candidates: cands.map((c, i) => ({ id: i + 1, source: c.source, box: c.box, ctrl: toCtrl(c.box), ...feat(c), ...(c.extra ?? {}) })),
     ...(cands.length === 0 ? { warn: '无候选：画面可能静止且低对比；换帧或走点选路径' } : {}),
+    ...(emitted.length ? { emitted: { dir: emitDir, count: emitted.length, files: emitted } } : {}),
     ...(pool.length > LIMIT
       ? { warn: '候选被上限截断：本区域池 ' + pool.length + ' 条，进表 ' + cands.length + ' 条。'
           + (roiApplied ? '用更小的 roi 继续收窄' : '给 roi 把搜索面收小（这是正解），或给 somLimit 放开上限') }
@@ -2787,16 +3532,33 @@ async function cmdCalibrate(args) {
 
 /* ────────────────────────── 消息分发 ────────────────────────── */
 const handlers = {
+  /* 活性探针：客户端调用超时后先问这个——能应答说明 daemon 事件循环没死，只是这条
+   * 调用超了；只失败该次调用，不杀进程（会话里的连接 / L0 / 事件环都保得住）。
+   * 必须是无状态纯应答：probe 是设备扫描、run_stop 有副作用，都不能借来探活。 */
+  ping: () => ({ ok: true, t: Date.now() }),
   init: (a) => {
     if (a.runDir) {
       S.runDir = String(a.runDir)
       S.previewPath = path.join(S.runDir, 'preview.png')
       try { fs.mkdirSync(S.runDir, { recursive: true }) } catch (e) { /* ignore */ }
+      /* action-frames 无 kf 配额：一次性 CLI 每条 click 都落 2 张，纯累积会膨胀。
+       * 不动当前运行——只清 >24h 的（上一个会话的残留）。 */
+      try {
+        const root = path.join(S.runDir, 'action-frames')
+        if (fs.existsSync(root)) {
+          const cutoff = Date.now() - 24 * 3600 * 1000
+          for (const f of fs.readdirSync(root)) {
+            const st = fs.statSync(path.join(root, f))
+            if (st.mtimeMs < cutoff) fs.unlinkSync(path.join(root, f))
+          }
+        }
+      } catch (e) { /* ignore */ }
     }
     if (Number(a.kfQuotaBytes) > 0) S.kfQuota = Math.floor(Number(a.kfQuotaBytes))
     return { ok: true, previewPath: S.previewPath, daemonId: S.daemonId, framesDir: kfRoot(), kfQuota: S.kfQuota }
   },
   probe: cmdProbe,
+  screencap_probe: cmdScreencapProbe,
   device_list: (a) => cmdDeviceList(a.kind),
   connect: cmdConnect,
   disconnect: cmdDisconnect,
@@ -2804,6 +3566,7 @@ const handlers = {
   stream_start: cmdStreamStart,
   stream_stop: cmdStreamStop,
   stream_status: cmdStreamStatus,
+  events_list: cmdEventsList,
   frame_get: cmdFrameGet,
   frame_diff: cmdFrameDiff,
   wait: cmdWait,
@@ -2822,7 +3585,72 @@ const handlers = {
 
 /* 子进程模式：stdin JSON 行协议（每行一条消息）。非 --child（headless 单测 import）不挂监听。 */
 if (CHILD) {
+  /* 兜底回收 agent 子进程：cleanupAgents 正常走 shutdown / run 重入，但 daemon 被 kill、
+   * 崩溃或宿主超时硬杀时没人收——实测会留下成批孤儿 agent 子进程占着设备连接。
+   * exit 里同步走 spawnSync taskkill /T + ident sweep——正常路径走 cleanupAgents
+   * 的完整版，这里是"进程突然死"的防泄漏，不能因为宿主死了就把 agent 树留给系统。 */
+  const killAgentChildrenSync = () => {
+    const bind = S.agentBind
+    if (!bind) return
+    for (const c of bind.clients) {
+      if (process.platform === 'win32') {
+        const root = c.child && c.child.pid
+        if (!root) continue
+        try { spawnSync('taskkill', ['/pid', String(root), '/T', '/F'], { timeout: 8000 }) } catch (e) { /* ignore */ }
+        if (c.ident) {
+          const like = '%' + String(c.ident).replace(/'/g, '') + '%'
+          const ps = '$self=$PID;Get-CimInstance Win32_Process|Where-Object{$_.ProcessId -ne $self -and $_.CommandLine -and $_.CommandLine -like \'' + like + '\'}|ForEach-Object{try{Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue}catch{}}'
+          try { spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps], { timeout: 15000 }) } catch (e) { /* ignore */ }
+        }
+      } else {
+        try { process.kill(-c.child.pid, 'SIGKILL') } catch (e) { try { c.child.kill('SIGKILL') } catch (e2) { /* ignore */ } }
+      }
+    }
+  }
+  process.on('exit', killAgentChildrenSync)
+  process.on('uncaughtException', (e) => {
+    killAgentChildrenSync()
+    /* 不吞掉异常：打印后让进程照常死，exit 里再收一次（幂等） */
+    console.error('daemon 未捕获异常：' + String(e && e.stack || e))
+    process.exit(2)
+  })
   const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity })
+  /* 宿主已死 = stdin 管道断开：daemon 不自杀就成孤儿（实测 --session-stop 杀的是会话服务
+   * 进程，daemon 还活着、它桥接的 agent 树也活着）。收到 close 就按 shutdown 同等规格
+   * 收摊：停流 → 树杀 agent → 退。兜底 10s：cleanup 卡住也不许吊着。 */
+  let hostGone = false
+  const onHostGone = () => {
+    if (hostGone) return
+    hostGone = true
+    Promise.resolve()
+      .then(() => cmdStreamStop())
+      .then(() => cleanupAgents())
+      .catch(() => { /* ignore */ })
+      .then(() => process.exit(0))
+    setTimeout(() => process.exit(0), 10000).unref()
+  }
+  rl.on('close', onHostGone)
+  /* 宿主已死 ≠ rl close / stdin end：实测两条都不触发（Node readline 在管道另一侧
+   * 被 kill 时不给 end）。管道破开走 stdin 的 error/close；再补一条兜底轮询：
+   * stdin 不再可读（readableEnded 或 destroyed）就按宿主死了走。 */
+  process.stdin.on('end', onHostGone)
+  process.stdin.on('error', onHostGone)
+  process.stdin.on('close', onHostGone)
+  /* 兜底轮询两条路：
+   * ① stdin 状态：宿主正常退出（不是被 kill）时管道还给 end/close；
+   * ② 宿主进程死了：Windows 下 process.kill(pid) = TerminateProcess，管道
+   *    一侧直接没，任何 stdin 事件都不来（实测 end/close/error 全不触发）。
+   *    ppid 存活探测是唯一可靠信号——宿主死了 1s 内 daemon 自杀收摊。 */
+  const hostPid = process.ppid
+  const stdinProbe = setInterval(() => {
+    try {
+      if (process.stdin.destroyed || process.stdin.readableEnded) { onHostGone(); return }
+      if (hostPid) {
+        try { process.kill(hostPid, 0) } catch (e) { onHostGone() }
+      }
+    } catch (e) { /* ignore */ }
+  }, 500)
+  stdinProbe.unref()
   rl.on('line', (line) => {
     let m = null
     try { m = JSON.parse(line) } catch (e) {
@@ -2843,8 +3671,10 @@ if (CHILD) {
 /* 纯函数导出（供 headless 验证直接断言，子进程运行中不使用）。
  * S 一并导出：l0EvictToBudget 等维护函数作用于模块态，单测需直改后还原。 */
 export const __test = {
-  pngDecode, pngEncodeRGB, downscale, blockAnalyze, blockHash, hashDist,
+  pngDecode, pngEncodeRGB, pngHeaderSize, downscale, blockAnalyze, blockHash, hashDist,
   regionOfBlocks, tightenBounds, tightenBoundsByEdges, edgeMap, cropRgb, connComponents, edgeDensityBoxes,
   readKfCropSource, buildL2Provenance, pickBalancedCandidates, pickNodeName, readRoi,
-  l0EvictToBudget, cmdKfPromote, cmdTplCrop, kfUsageBytes, defaultOutFile, S,
+  l0EvictToBudget, cmdKfPromote, cmdTplCrop, kfUsageBytes, defaultOutFile, eventFrameAnchor, S,
+  pickRecoBox, pickActionBox, anchorFromCacheDedup, checkExpect, blockHash, hashStr,
+  setupAgents, buildLinuxConfig,
 }