@thincoder/core 0.10.13 → 0.11.1

package/agent-tools/ssh-transport.mjs

@@ -9,26 +9,36 @@
  *
  * - askpass 链：包装档（Win `.cmd` ∥ POSIX `.sh` 0700）→ `tools/ssh-askpass.mjs` → stdout；秘密只经
  *   ssh 子进程环境 `TC_SSH_SECRET`（零入参 / 零落盘 / 零回显；环境经 `nodeChildEnv` 单点补 Electron 旗标）。
- * - 沉降：静默窗 800 ms ∥ 会话提示符正则命中 ⇒ 就绪；硬超时 10 s ⇒ 部分输出 + 可读句（不静默挂起）。
- * - 遮蔽：写入的秘密对**捕获面与日志面**做字面移除（跨 chunk 切分：保留 `len-1` 尾缓冲）。
+ * - 终端噪声：有状态剥离（CSI ∥ OSC ∥ 单字符控制三类 + CRLF 归一；状态跨 chunk 携带）——落点 = 传输入口，
+ *   **先剥离后遮蔽**；日志面 = 模型面同源（D-TO23）。
+ * - 就绪判据：四门（待答标记 ∥ 提示符 ∥ 仍在吐 ∥ 硬超时 60 s）；静默窗只作去抖（D-TO21）。
+ * - 遮蔽：写入的秘密对**捕获面与日志面**做字面移除（比较面 = 同一归一 + 按不可见处切段 ≥ 4）。
  * - 失败分类族（auth ∥ unreachable ∥ hostkey）照服务端 `src/sandbox/ssh.mjs` 同源判据。
- * 模块图：→ config.mjs（configDir 缺省）· tools/shared.mjs（解码 ∥ 清洗）· tools/node-child.mjs
- * （nodeChildEnv）——叶子向、无环（本档不 import `ssh-session.mjs`）。
+ * 模块图：→ config.mjs（configDir 缺省）· tools/shared.mjs（解码）· text-budget.mjs（截断本体）·
+ * tools/node-child.mjs（nodeChildEnv）· expand-home.mjs（`~` 展开单源——`identityFile` 用）——叶子向、无环
+ * （本档不 import `ssh-session.mjs`）。
  */
 import { chmodSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs"
 import { spawn } from "node:child_process"
-import { homedir } from "node:os"
 import { fileURLToPath } from "node:url"
 import { configDir } from "../config.mjs"
-import { makeDecoder, sanitizeOutput } from "../tools/shared.mjs"
+import { expandHome } from "../expand-home.mjs"
+import { makeDecoder } from "../tools/shared.mjs"
 import { nodeChildEnv } from "../tools/node-child.mjs"
+import { capText as capBudgetText, fillMarker } from "../text-budget.mjs"
 
-/** 静默窗（§6.22 ③）：到点无新输出 ⇒ 判定就绪。 */
+/** 静默窗（§6.22 ③）：**只作去抖**——判尾部这半条标记到没到齐；不再单独构成「已就绪」。 */
 export const SSH_SETTLE_MS = 800
-/** 硬超时（§6.22 ③/⑥）：到点返回部分输出 + 可读句。 */
-export const SSH_TIMEOUT_MS = 10_000
-/** 单次返回帽（§6.22 ⑥）：保尾 + 截断注记；全量恒在 log。 */
+/** 硬超时（§6.22 ③/⑥）：`send` / `read` / `secret_input` 的本次等待；到点返回部分输出 + 可读句。 */
+export const SSH_TIMEOUT_MS = 60_000
+/** `connect` 首屏等待（§6.22 ③「适用范围」拆两常量——慢设备才拖不动连接）。 */
+export const SSH_CONNECT_SETTLE_MS = 10_000
+/** 单次返回帽（§6.22 ⑥）：**返回窗口** = 保头 + 注记 + 保尾；省略中段回填未读缓冲。 */
 export const SSH_RETURN_CAP = 8000
+/** 帽窗头尾比例（§6.22 ⑥：头 60% ∥ 尾 40%——头段装接口 / ACL，尾段装结束证据）。 */
+const CAP_HEAD_RATIO = 0.6
+/** 遮蔽分段下限（§6.22 ③「`≥ 4` 为选定策略值」：3 字符以下与正常输出撞面过高）。 */
+const MASK_SEG_MIN = 4
 /** 保活缺省（§6.22 ④：`ServerAliveInterval=30`；测试态时间缝按 ms 传入后换算）。 */
 export const SSH_KEEPALIVE_MS = 30_000
 /** 秘密环境变量名（§6.22 ②「秘密传递」行）。 */
@@ -84,13 +94,6 @@ export function buildSshEnv({ wrapper, secret }) {
   return nodeChildEnv(env)
 }
 
-/** `~` 展开（`identityFile` 记录 / 参数——`~/.ssh/id_ed25519` 同式；非 `~` 开头原样）。 */
-function expandHome(file) {
-  const raw = String(file ?? "")
-  if (!/^~(?=$|[\\/])/.test(raw)) return raw
-  return `${homedir()}${raw.slice(1)}`
-}
-
 /** 会话命令形（§6.22 ⑤）：`-tt` 强制远端 PTY + 保活三件 + 单提示；`port`/`user` 未给 ⇒ 不下发。
  *  `identityFile` 显式给出 / 记录有值 ⇒ `-i <路径>`（追加候选身份，不夺本机配置与 agent 的既有尝试序列）。
  *  预探 = `NumberOfPasswordPrompts=0`（password ∥ keyboard-interactive 两径同被短路——
@@ -110,19 +113,111 @@ export function buildSshArgs({ host, user, port, probe, identityFile = null, kee
   ]
 }
 
+// ─── 终端噪声（§6.22 ③「终端噪声」· D-TO23）────────────────────────────────
+
+/** 不可见处（遮蔽比较面的切段器——与剥离同一类目：CSI ∥ ESC+1 ∥ 任一控制字符）。 */
+const INVISIBLE_SPLIT = /\x1b\[[\x20-\x3f]*[\x40-\x7e]|\x1b[^\x1b]?|[\x00-\x1f\x7f]/
+
+/** 有状态剥离器（§6.22 ③）：三类序列 CSI ∥ OSC ∥ 单字符控制 + `\r\n`∥裸 `\r` 归 `\n`。
+ *  状态跨 chunk 携带（序列被 chunk 边界切开不残留成字面）；三类之外的序列（DCS / APC 等）按
+ *  单字符控制处理——头字节剥掉，体内字节当可见文本如实交出（设计「表外序列的出口」）。
+ *  `push` = 返回边界（状态保留）；`end` = 收场（硬超时 ∥ close ∥ 会话终结：尾部半条序列丢弃并计一次）。 */
+export function createStripper() {
+  let state = "ground" // ground ∥ esc ∥ csi ∥ osc ∥ oscEsc ∥ charset
+  let pendingCr = false // chunk 尾的 `\r`（下一片首字为 `\n` ⇒ 仍归一条——跨 chunk 的 CRLF）
+  const scan = (text) => {
+    const s = String(text ?? "")
+    let out = ""
+    let i = 0
+    while (i < s.length) {
+      const ch = s[i]
+      if (pendingCr) {
+        pendingCr = false
+        out += "\n"
+        if (ch === "\n") { i += 1; continue }
+      }
+      if (state === "esc") {
+        state = "ground"
+        if (ch === "[") state = "csi"
+        else if (ch === "]") state = "osc"
+        else if (ch === "(" || ch === ")" || ch === "*" || ch === "+") state = "charset"
+        else if (ch === "\x1b") state = "esc"
+        i += 1
+        continue
+      }
+      if (state === "charset") { state = "ground"; i += 1; continue } // `ESC ( 0` 字符集指定（既有覆盖不回归）
+      if (state === "csi") {
+        const c = ch.charCodeAt(0)
+        if (c >= 0x20 && c <= 0x3f) { i += 1; continue } // 参数 ∥ 中间字节
+        if (c >= 0x40 && c <= 0x7e) { state = "ground"; i += 1; continue } // 终字节
+        state = "ground" // 类外字 ⇒ 序列作废，本字按常规面重判（不吞可见字节）
+        continue
+      }
+      if (state === "osc") {
+        if (ch === "\x07") { state = "ground"; i += 1; continue }
+        if (ch === "\x1b") { state = "oscEsc"; i += 1; continue }
+        i += 1
+        continue
+      }
+      if (state === "oscEsc") {
+        state = "ground"
+        if (ch === "\\") { i += 1; continue } // `ESC \` = ST
+        state = "osc" // 非 ST ⇒ 本字仍在 OSC 体内（ESC 已丢弃，体内字节本就要丢）
+        continue
+      }
+      if (ch === "\x1b") { state = "esc"; i += 1; continue }
+      if (ch === "\r") {
+        if (i + 1 >= s.length) { pendingCr = true; i += 1; continue }
+        out += "\n"
+        i += s[i + 1] === "\n" ? 2 : 1
+        continue
+      }
+      if (ch === "\n" || ch === "\t") { out += ch; i += 1; continue }
+      const code = ch.charCodeAt(0)
+      if (code < 0x20 || code === 0x7f) { i += 1; continue } // BEL ∥ 退格 ∥ 其余 C0（保留 `\n` / `\t`）
+      out += ch
+      i += 1
+    }
+    return out
+  }
+  return {
+    /** 喂一片（返回可交出文本；半条序列留给下一片）。 */
+    feed(text) { return scan(text) },
+    /** 收场：尾部半条序列丢弃并计一次；其前后的可见字节照常交出。 */
+    end(text = "") {
+      let out = scan(text)
+      if (pendingCr) { out += "\n"; pendingCr = false }
+      const dropped = state === "ground" ? 0 : 1
+      state = "ground"
+      return { text: out, dropped }
+    },
+  }
+}
+
+/** 同一归一（无状态旁路——遮蔽比较面用：秘密值先过控制字节剥离 + CRLF 归一）。 */
+export function normalizeText(text) {
+  return createStripper().end(String(text ?? "")).text
+}
+
 // ─── 遮蔽（§6.22 ⑦）────────────────────────────────────────────────────────
 
-/** 秘密遮蔽过滤器：字面移除 + `len-1` 尾缓冲（跨 chunk 切分不泄；尾至沉降冲涮）。 */
+/** 秘密遮蔽过滤器：字面移除 + `len-1` 尾缓冲（跨 chunk 切分不泄；尾至沉降冲涮）。
+ *  比较面 = 与剥离同一归一（§6.22 ③）：秘密值先归一、再按不可见处切段（段长 ≥ 4）——
+ *  裸字面匹配会漏掉夹控制字节 ∥ 被 chunk 切开的回显。 */
 export function createMask() {
   const secrets = []
   let tail = ""
   let keep = 0
   return {
     add(secret) {
-      const s = String(secret ?? "")
-      if (!s || secrets.includes(s)) return
-      secrets.push(s)
-      keep = Math.max(keep, s.length - 1)
+      const raw = String(secret ?? "")
+      if (!raw) return
+      const table = [normalizeText(raw), ...raw.split(INVISIBLE_SPLIT).filter((seg) => seg.length >= MASK_SEG_MIN)]
+      for (const s of table) {
+        if (!s || secrets.includes(s)) continue
+        secrets.push(s)
+        keep = Math.max(keep, s.length - 1)
+      }
     },
     push(text) {
       let out = tail + String(text ?? "")
@@ -132,6 +227,8 @@ export function createMask() {
       tail = out.slice(out.length - keep)
       return emit
     },
+    /** 尾缓冲现行内容（**判据面用**：门①② 要看到已达字节——尾在 drain 时释放，判据不得被它推迟）。 */
+    peek() { return tail },
     /** 沉降时冲涮尾缓冲：**只放行非秘密前缀段**（尾内最长可疑后缀一律扣下——整尾 ∥ 移位前缀
      *  都不出返回面；扣下的至多 `秘密长-1` 字符，代价 < 前缀外泄）。 */
     flush() {
@@ -150,10 +247,9 @@ export function createMask() {
 
 // ─── 子进程（起跑 ∥ 双流汇入 ∥ 退出）────────────────────────────────────────
 
-/** 悬挂 chunk 双流汇入（遮蔽 → log ∥ 缓冲 ∥ 面板 → 唤醒沉降等待者）。 */
+/** 悬挂 chunk 双流汇入（已剥离已遮蔽 → log ∥ 缓冲 ∥ 面板 → 唤醒沉降等待者）。 */
 function handleChunk(entry, text) {
   if (!text) return
-  entry.bytes += text.length
   try { entry.logStream?.write(text) } catch { /* log 写失败不进语义——尽力面 */ }
   entry.buf += text
   if (entry.buf.length > BUF_KEEP_CHARS) {
@@ -165,18 +261,33 @@ function handleChunk(entry, text) {
   for (const w of [...entry._waiters]) w("data")
 }
 
-/** 子进程挂载（双流解码 ∥ 退出 ∥ spawn 错误——探连与会话同径）。 */
+/** 子进程挂载（双流解码 ∥ 剥离 → 遮蔽 ∥ 退出 ∥ spawn 错误——探连与会话同径）。
+ *  顺序 = **先剥离后遮蔽**（§6.22 ③）：剥离只删字节、不插入 ⇒ 切不断秘密字面；每条流一份剥离状态
+ *  （两个流各自成序列，不共用一个半条状态）。到达计数在这之前记（§6.22 ③ 门④ 口径 = 「回了没有」，
+ *  不随遮蔽尾缓冲的后扣而变）。 */
 export function attachChild(entry, child) {
   entry.child = child
   const outDecoder = makeDecoder()
   const errDecoder = makeDecoder()
-  const feed = (d) => handleChunk(entry, entry.mask.push(sanitizeOutput(d)))
+  const outStrip = createStripper()
+  const errStrip = createStripper()
+  entry.strippers = [outStrip, errStrip]
+  const route = (decoder, strip) => (d, final = false) => {
+    const visible = strip.feed(decoder(d, final))
+    if (!visible) return
+    entry.lastDataAt = Date.now()
+    entry.bytes += visible.length // 到达量（剥离后、遮蔽前）——门④ 判「回了没有」用
+    handleChunk(entry, entry.mask.push(visible))
+  }
+  const outRoute = route(outDecoder, outStrip)
+  const errRoute = route(errDecoder, errStrip)
   const flush = () => {
-    const rest = sanitizeOutput(outDecoder(Buffer.alloc(0), true)) + sanitizeOutput(errDecoder(Buffer.alloc(0), true))
-    if (rest) feed(Buffer.from(rest, "utf8"))
+    outRoute(Buffer.alloc(0), true)
+    errRoute(Buffer.alloc(0), true)
+    entry.escDropped = (entry.escDropped ?? 0) + flushEscapes(entry) // 收场：尾部半条序列丢弃并计一次
   }
-  child.stdout.on("data", (d) => feed(outDecoder(d)))
-  child.stderr.on("data", (d) => feed(errDecoder(d)))
+  child.stdout.on("data", (d) => outRoute(d))
+  child.stderr.on("data", (d) => errRoute(d))
   // stdin 无 error 监听 ⇒ 对端刚死时写入的异步 EPIPE 会以未处理 'error' 事件逸出（uncaughtException）。
   // 同族先例：CLI `tui/clipboard.mjs` ∥ `mcp/transport-stdio.mjs` 同式吞 EPIPE。
   child.stdin?.on("error", () => { /* 写失败由 send ∥ secret_input 的调用面回读；此处仅防未处理事件 */ })
@@ -210,17 +321,52 @@ export function spawnSession(entry, { user, port, secret, identityFile = null, k
   return child
 }
 
-// ─── 沉降（§6.22 ③）────────────────────────────────────────────────────────
+// ─── 就绪判据（§6.22 ③ 四门 · D-TO21）─────────────────────────────────────
+
+/** 待答标记（门①——设备正等我发键；`--More--` 走空格、确认走 y/n）。 */
+const ANSWER_MARKERS = ["--More--", "(y/n)", "Password:"]
+/** 缺省设备提示符形（门②——行尾 `#` `>` `$` `%`，前接非空白词）。 */
+const DEVICE_PROMPT = /[^\s][#$>%]\s*$/u
+
+/** 末行（门① 只看末行——陈旧标记被后续输出顶走就不命中，B18）。 */
+const tailLine = (text) => {
+  const s = String(text ?? "")
+  return s.slice(s.lastIndexOf("\n") + 1)
+}
+
+/** 判据面文本 = **新到字节**（`base` 之后） + 遮蔽尾缓冲（尾在 drain 时释放，门不得被它推迟）。
+ *  `base` 撇掉本轮之前就在缓冲里的存量（回填的中段不得充当本轮判据面——§6.22 ③「四门只判新到字节」）。 */
+const watchText = (entry, base = 0) => `${entry.buf.slice(base)}${entry.mask?.peek?.() ?? ""}`
 
-function promptHit(entry) {
-  return Boolean(entry.promptRe && entry.promptRe.test(entry.buf))
+/** 门① 待答标记（**末行锚定**——只看最后一个换行之后的部分；"出现"故用 `includes`：`(y/n)?` ∥ `[y/n]` 同类形都能命中）。 */
+export function markerHit(entry, base = 0) {
+  const line = tailLine(watchText(entry, base))
+  return ANSWER_MARKERS.some((m) => line.includes(m))
 }
 
-/** 等到「就绪判据」成立：提示符命中 ∥ 静默窗到点 ∥ 硬超时 ∥ 退出 ∥ 中止（返回 reason）。 */
-export function waitSettled(entry, { timeoutMs = SSH_TIMEOUT_MS, signal = null } = {}) {
+/** 门② 提示符：agent 所设 `promptPattern` 命中 ∥ 缺省设备形。 */
+export function promptHit(entry, base = 0) {
+  const text = watchText(entry, base)
+  if (entry.promptRe && entry.promptRe.test(text)) return true
+  return DEVICE_PROMPT.test(tailLine(text))
+}
+
+/** 硬超时失败标签三枚（门④——与门③ 两条子情形同文；计的是**到达字节**：剥离后、遮蔽前）。 */
+function timeoutLabel(entry, startBytes) {
+  if (entry.bytes <= startBytes) return "not a single byte came back"
+  return Date.now() - entry.lastDataAt < SSH_SETTLE_MS ? "still producing output" : "no prompt detected"
+}
+
+/** 等到就绪（返回 reason）：`marker` ∥ `prompt` ∥ `timeout` ∥ `exited` ∥ `aborted`（`connect` 另有 `silence`）。
+ *  门①② 在**每个到达 chunk** 上求值；静默窗只判「尾部这半条标记到没到齐」（去抖）——不参与求值、不推迟
+ *  判断时点，也不再单独构成「已就绪」（D-TO21）。`settleOnSilence` = `connect` 首屏沿用旧口径
+ *  （§6.22 ③「适用范围」：四门只判 `send` / `read` / `secret_input`）。 */
+export function waitSettled(entry, { timeoutMs = SSH_TIMEOUT_MS, signal = null, settleOnSilence = false } = {}) {
   return new Promise((resolve) => {
     let done = false
     let quietTimer = null
+    const startBytes = entry.bytes
+    const baseLen = entry.buf.length // 门①② 只判**新到字节**（存量中段不当本轮判据面）
     const deadline = Date.now() + Math.max(1, Number(timeoutMs) || SSH_TIMEOUT_MS)
     const finish = (reason) => {
       if (done) return
@@ -229,15 +375,28 @@ export function waitSettled(entry, { timeoutMs = SSH_TIMEOUT_MS, signal = null }
       clearTimeout(deadlineTimer)
       signal?.removeEventListener("abort", onAbort)
       entry._waiters.delete(onEvent)
+      if (reason === "timeout") {
+        entry.settleFailure = timeoutLabel(entry, startBytes)
+        entry.escDropped = (entry.escDropped ?? 0) + flushEscapes(entry) // 硬超时 = 收场边界（§6.22 ③ flush②）
+      }
       resolve(reason)
     }
+    const evaluate = () => {
+      if (markerHit(entry, baseLen)) { finish("marker"); return true }
+      if (promptHit(entry, baseLen)) { finish("prompt"); return true }
+      return false
+    }
     const arm = () => {
       clearTimeout(quietTimer)
-      quietTimer = setTimeout(() => finish(promptHit(entry) ? "prompt" : "silence"), SSH_SETTLE_MS)
+      quietTimer = setTimeout(() => {
+        if (done) return
+        if (settleOnSilence) return finish(promptHit(entry, baseLen) ? "prompt" : "silence")
+        evaluate() // 去抖：尾部半条标记到齐后再求值一次；未命中 ⇒ 继续等到硬超时
+      }, SSH_SETTLE_MS)
     }
     const onEvent = (kind) => {
       if (kind === "exit") return finish("exited")
-      if (promptHit(entry)) return finish("prompt")
+      if (evaluate()) return undefined
       arm()
     }
     const onAbort = () => finish("aborted")
@@ -246,15 +405,21 @@ export function waitSettled(entry, { timeoutMs = SSH_TIMEOUT_MS, signal = null }
     if (signal?.aborted) return finish("aborted")
     signal?.addEventListener("abort", onAbort, { once: true })
     entry._waiters.add(onEvent)
-    onEvent("data") // 起点：先查提示符，否则起静默窗（「send 后 800 ms 无新输出」从本刻起算）
+    onEvent("data") // 起点：先查门①②，否则起去抖窗
   })
 }
 
-/** 就绪结论注记（§6.22 ③：静默 ∥ 提示符 ∥ 超时——超时带 id / host / 已等时长，不静默挂起）。 */
+/** 就绪结论注记（§6.22 ③）：提示符 ∥ 待答标记 ∥ 硬超时（**点名失败门**）∥ 中断 ∥ 退出。 */
 export function settleNote(entry, reason, waitedMs) {
   if (reason === "prompt") return "settled (prompt matched)"
+  if (reason === "marker") return "settled (the device is waiting for input — the marker is shown above)"
   if (reason === "silence") return "settled (silence window)"
-  if (reason === "timeout") return `not settled after ${Math.round(waitedMs / 100) / 10}s (${idLabel(entry)} @ ${entry.host}) — partial output above (silence window or promptPattern never hit)`
+  if (reason === "timeout") {
+    const label = entry.settleFailure ?? "no prompt detected"
+    entry.settleFailure = null
+    const hint = label === "no prompt detected" ? "; pass promptPattern on connect if this device's prompt does not look like a shell prompt" : ""
+    return `not settled after ${Math.round(waitedMs / 100) / 10}s (${idLabel(entry)} @ ${entry.host}) — partial output above (${label}${hint})`
+  }
   if (reason === "aborted") return `(interrupted — partial output above; the session stays open: ${idLabel(entry)} @ ${entry.host})`
   if (reason === "exited") return `${idLabel(entry)} @ ${entry.host} ${entry.state === "ready" ? "ended (the remote closed the connection)" : "has stopped"}`
   return String(reason)
@@ -275,12 +440,78 @@ export function drain(entry) {
   return { text, dropped }
 }
 
-/** 返回帽（保尾 + 截断注记——§6.22 ⑥）。 */
-export function capText(text, max = SSH_RETURN_CAP, entry = null) {
-  if (text.length <= max) return text
-  const omitted = text.length - max
-  const where = entry?.logPath ? ` — full output in the log: ${entry.logPath}` : ""
-  return `[... first ${omitted} chars omitted (return cap ${max})${where}]\n${text.slice(text.length - max)}`
+/** 回填未读缓冲（丢最旧、保住尾证据；§6.22 ⑥）。 */
+function backfill(entry, middle) {
+  if (!middle || !entry) return
+  entry.buf = middle + entry.buf // 中段先于更新字节（回填顺序 = 原序）
+  if (entry.buf.length > BUF_KEEP_CHARS) {
+    entry.buf = entry.buf.slice(entry.buf.length - BUF_KEEP_CHARS)
+    entry.bufDropped = true
+  }
+}
+
+/** 返回帽窗（§6.22 ⑥ · D-TO22）：**返回总长 ≤ 帽（注记计入帽内）**——头 60% ∥ 注记 ∥ 尾 40%，
+ *  切点按行边界取整、取整只在头段（头段可少不可多）；省略中段**回填未读缓冲**（下一次 `read` 先交出）
+ *  ⇒ 长配置按窗口连续取全，不靠翻日志。截断本体 = `text-budget.mjs` `capText`（零新截断实现）。 */
+export function capWindow(entry, text, max = SSH_RETURN_CAP) {
+  const t = String(text ?? "")
+  if (!(max > 0) || t.length <= max) return t
+  if (max <= windowMarker(t.length, 0, 0).length) {
+    // 帽小到放不下注记 ⇒ 无法成窗：按帽交出前缀、余量回填缓冲（「总长 ≤ 帽」不变式先行；每次 read 都有进展）
+    backfill(entry, t.slice(max))
+    return t.slice(0, max)
+  }
+  let marker = windowMarker(t.length, 0, 0)
+  let head = 0
+  let tail = 0
+  for (let round = 0; round < 6; round++) {
+    const budget = Math.max(0, max - marker.length)
+    const nextHead = alignHead(t, Math.floor(budget * CAP_HEAD_RATIO))
+    const nextTail = Math.max(0, budget - Math.floor(budget * CAP_HEAD_RATIO))
+    const nextMarker = windowMarker(t.length - nextHead - nextTail, nextHead, nextTail)
+    const same = nextHead === head && nextTail === tail && nextMarker === marker
+    head = nextHead
+    tail = nextTail
+    marker = nextMarker
+    if (same) break
+  }
+  while (head > 0 && head + marker.length + tail > max) { // 收敛后的边角（省略数位数增长）——头段再收
+    head = Math.max(0, head - (head + marker.length + tail - max))
+    marker = windowMarker(t.length - head - tail, head, tail)
+  }
+  backfill(entry, t.slice(head, t.length - tail))
+  const markerOf = (omitted) => windowMarker(omitted, head, tail)
+  return capBudgetText(t, { max, keepHead: head, keepTail: tail, marker: markerOf })
+}
+
+/** 注记形（§6.22 ⑥）：`N` 走 `text-budget.mjs` `fillMarker` 占位约定；`H` ∥ `T` = 实保头 ∥ 尾长。 */
+const WINDOW_MARKER = "[… N chars omitted (head H / tail T) — the omitted middle is kept; call read again to collect it …]\n"
+const windowMarker = (omitted, head, tail) =>
+  fillMarker(WINDOW_MARKER, omitted).replace("H", String(head)).replace("T", String(tail))
+
+/** 头段切点按行边界取整（不切半行；找不到换行则保持原位——头段可少不可多）。 */
+const alignHead = (text, n) => {
+  const nl = text.lastIndexOf("\n", Math.max(0, n - 1))
+  return nl >= 0 ? nl + 1 : n
+}
+
+/** 半条序列的收场（§6.22 ③ flush②）：尾部半条丢弃并计一次；其前后的可见字节照常交出。 */
+export function flushEscapes(entry) {
+  let dropped = 0
+  for (const strip of entry.strippers ?? []) {
+    const res = strip.end()
+    if (res.text) handleChunk(entry, entry.mask.push(res.text))
+    dropped += res.dropped
+  }
+  return dropped
+}
+
+/** 半条序列收场注记（§6.22 ③ flush②）——报告一次即清零。 */
+export function escapeNote(entry) {
+  const n = entry.escDropped ?? 0
+  if (!n) return ""
+  entry.escDropped = 0
+  return `\n— ${n} incomplete escape sequence dropped`
 }
 
 /** 状态行冠形（§6.22 动作表末行）：每返回首行。 */

package/agent-tools/subagent-actions-query.mjs

@@ -30,7 +30,7 @@ import { unsettledRow, unsettledRows } from "../agent/digest-account.mjs"
  * - id omitted → { overview: { running: [...], queued: [...], done: [...],
  *   unsettled: [{id, role, state, attempts, preview?}] } } — live queue positions (index in
  *   _asyncQueue + 1); the unsettled section lists every entry still awaiting settlement
- *   (awaiting-digest / retrying) plus the upgraded ledger (§6.31.6).
+ *   (awaiting-digest / unaccounted) plus the upgraded ledger (§6.31.6).
  * AGENT-LOOP-SUBAGENT.md §6.7.2: running 条目带 touched files 摘要（touchedFiles 前 5 + touchedMore 超出
  * 计数——相对查询方 cwd；0 改动 → touched 占位）；queued 条目带 touched 占位
  * "—（未启动）"；done/error/取消条目无 touched 字段（round3 #9）。

package/agent-tools/subagent-actions.mjs

@@ -245,7 +245,7 @@ function touchedFilesNote(child, cwd) {
   const touched = child?._touchedFiles ?? []
   if (touched.length === 0) return ""
   const shown = touched.map((f) => {
-    const r = relative(cwd ?? process.cwd(), f)
+    const r = relative(cwd, f)
     return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
   })
   return `\nTouched files: ${shown.join(", ")}`

package/agent-tools/subagent-async.mjs

@@ -63,8 +63,9 @@ export const ASYNC_POOL_LIMITS = { engCoder: 4, other: 4 }
 
 /**
  * Role → pool domain (single source of truth — §6.10 修正 #8): the CLI role
- * whitelist is subagent.mjs's ROLES = { explore, plan, coder, eng-coder, eng-designer }
- * (mode-filtered: normal → explore/plan/coder, engineering → explore/eng-designer/eng-coder).
+ * whitelist is subagent.mjs's ROLES = { explore, plan, coder, eng-coder, eng-designer, tester }
+ * (mode-filtered: normal → explore/plan/coder/tester, engineering → explore/eng-designer/eng-coder/tester —
+ * tester is dispatchable in both modes).
  * eng-coder → engCoder pool; every other role (including unknown roles — fail-safe)
  * → other pool. escalate spawns its expert internally (role "coder" — other pool).
  */

package/agent-tools/subagent-scheduler.mjs

@@ -3,19 +3,24 @@
  * subagent-async.mjs 拆分——Module Split Policy——纯迁移零行为变化——
  * AGENT-LOOP-SUBAGENT.md §6.9 D-SD1..SD5 + D-SL1 环形死锁修正）。
  * 内容：normalizeFileList / filesOverlap / effectiveFiles（SCHEDULER-DYNAMIC-DOMAIN
- * 动态域——声明 ∪ running touched）/ depInfo / describeBlockers / detectStall（
+ * 动态域——声明 ∪ running touched）/ depInfo / describeBlockers / batchDocInFlight（
+ * AGENT-LOOP-SUBAGENT.md §6.58 批次档复用护栏——按档查在飞占用者）/ detectStall（
  * P-SL2 停滞机械检测）/ queueRunnable / assertNoDepCycle / dependentLabels /
  * refreshQueuedTokens / maybeRefillAsync。
  * ASYNC_POOL_LIMITS/poolLimitsFor/runningPoolCount 回引自 subagent-async.mjs（主体保有——
  * 仅调用期使用——与主体对此处调度符号的回引构成惰性环——无求值期依赖）。
  */
-import { isAbsolute, relative, resolve } from "node:path"
+import { isAbsolute, relative } from "node:path"
 import { existsSync, statSync } from "node:fs"
 // zero-block 批 P1（TUI.md §6.8.3.2②）：排队刷新 relay 异常留痕（禁静默——池状态仍不破坏）。
 import { logEvent } from "../log.mjs"
 // M5 F6（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：files 声明面拦截谓词本体落
 // spawn-gates.mjs（纯谓词零依赖——本处只加 import 调用，无环）。
-import { rejectEngineeringFilePaths } from "./spawn-gates.mjs"
+import { rejectProcessDocPaths } from "./spawn-gates.mjs"
+// `files` 落点单源 = 统一解析层（`docs/core/design/PATH-RESOLUTION.md` §2.5 第 4 行：`kind:"none"` /
+// `order:"near-first"` ⇒ 恒解析出、只做调度、不校验存在性）。门判（目录声明 / 过程档）
+// 仍吃**原始声明形状**——判据在转绝对之前跑，顺序零改。
+import { resolvePathTarget } from "../path-resolve.mjs"
 import { poolLimitsFor, runningPoolCount, ASYNC_POOL_LIMITS } from "./subagent-async.mjs"
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor——async-settle.mjs 反向 import 本模块
 // （dependentLabels）构成同款惰性环（函数级绑定——无求值期依赖）。
@@ -43,7 +48,7 @@ import { carrierField, getAsyncPool, tombstoneOf } from "./async-settle.mjs"
  *  大小写不敏感（todo.md/changelog.md 精确——路径任意层含 docs/、根、.thincoder/）——
  *  命中 → throw（fail-closed——先于调度器准入——无排队残留——错误即工具结果）；
  *  提示列出全部违规条目——英文模板逐字定稿（AGENT-LOOP-SUBAGENT.md §6.9「父侧文件拦截（R26）」）。
- *  M5 F6（2026-09-17——2026-10-15 口径随正）：黑名单随同迁入 spawn-gates.mjs（rejectEngineeringFilePaths——族 = 过程档（CHANGELOG）+ 工程工具面（`scripts/*`——层级锚定：仅仓根与直接子层；目录名在深层不携带 face 信息）；老台账 md 族随 M2 退役）——本函数只留调用（错误文案逐字保留）。 */
+ *  M5 F6（2026-09-17——2026-10-15 口径随正）：黑名单随同迁入 spawn-gates.mjs（族 = 过程档（CHANGELOG）+ 项目状态档（PROJECT-MANIFEST.json）；老台账 md 族随 M2 退役）——本函数只留调用（错误文案逐字保留）。 */
 export function normalizeFileList(files, cwd) {
   const out = []
   for (const f of Array.isArray(files) ? files : []) {
@@ -51,17 +56,19 @@ export function normalizeFileList(files, cwd) {
     if (f.trimEnd().endsWith("/") || f.trimEnd().endsWith("\\")) { // 2.7 批：尾随空格目录声明（"test/ "）同拒
       throw new Error(`files must be file-level paths — directory declarations are not supported: ${f}`)
     }
-    const abs = resolve(cwd ?? process.cwd(), f)
+    // 落点由统一解析层给（`kind:"none"` / `order:"near-first"` ⇒ 恒解析出、只做调度）；
+    // **门判仍吃原始声明 `f`**：目录声明的尾分隔符判据按声明形状判——转成绝对路径后再判会漏。
+    const abs = resolvePathTarget(cwd, f, { kind: "none", order: "near-first" }).abs
     if (existsSync(abs) && statSync(abs).isDirectory()) {
       throw new Error(`files must be file-level paths — directory declarations are not supported: ${f}`)
     }
     if (!out.includes(abs)) out.push(abs)
   }
-  // M5 F6（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2——2026-10-15 口径随正）：`scripts/*`（仅仓根/直接子层）+ 过程档拦截——
-  // 谓词本体落 spawn-gates.mjs（rejectEngineeringFilePaths 收集全部违规 + 抛合并错误）；
+  // M5 F6（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2——2026-10-15 口径随正）：过程档 / 项目状态档拦截——
+  // 谓词本体落 spawn-gates.mjs（收集全部违规 + 抛合并错误）；
   // 循环内目录声明先行（错误序不变——目录错误先于过程档错误）。父侧维护文件
   // basename 族（CHANGELOG——`ledger.db` 随 M2 退役）随同迁入谓词——错误文案逐字保留。
-  if (files !== undefined && files !== null) rejectEngineeringFilePaths(files)
+  if (files !== undefined && files !== null) rejectProcessDocPaths(files)
   return out
 }
 
@@ -79,7 +86,7 @@ export function filesOverlap(a, b) {
 
 /** 冲突文件的显示形态（优先相对 cwd——面板/返回文本可读）。 */
 function showFile(parent, key) {
-  const cwd = parent.cwd ?? process.cwd()
+  const cwd = parent.cwd
   const rel = relative(cwd, key)
   return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : key
 }
@@ -176,6 +183,33 @@ export function describeBlockers(parent, entry) {
   return { kind: "slot", detail: "" }
 }
 
+/**
+ * AGENT-LOOP-SUBAGENT.md §6.58 批次档复用护栏（2026-10-28 batchdoc-reuse-guard）——
+ * 按档查在飞占用者：池内条目 `_batchDoc` 与 `batchDocAbs` 按 `fileKey` 相等且**在飞**
+ * ⇒ `{ id, role, status }`；无 ⇒ `null`。池派生事实单源在此（与 `depInfo` /
+ * `describeBlockers` 同族），消费方单点 = `buildSpawnChild` 的 `batchDoc` 门。
+ * 三条判据各防一个具体的错：① 池**经访问器读**（`getAsyncPool`，读法同 `depInfo`）——
+ * 裸读 `parent._asyncSubagents` 在只携 `history` 的合成 parent 上读到空池 ⇒ 护栏不报错、
+ * 不生效、没人知道；② **按 status 过滤**（`done` / `cancelled` 皆假）——正常 settle 的条目
+ * 留在池里（`async-settle.mjs:295`）⇒ 只看「池里有同档条目」会把单席顺序交接全部误拒；
+ * ③ **占用判据只认 `_batchDoc`、不分角色**（普通面 coder 携档也算），而被检面只有工程角色的
+ * spawn、sync spawn 不入池也不是占用者（同档 §6.58.7 第 7 条）——**这个不对称勿「顺手统一」**。
+ * 入参 = 已解析的绝对路径（唯一消费方 `buildSpawnChild` 的工程分支，路径由 `resolveBatchReadPath`
+ * 保证非空）；空入参返 `null` = 「无路径可比」——本谓词不替调用方判「该不该传路径」。
+ */
+export function batchDocInFlight(parent, batchDocAbs) {
+  if (!batchDocAbs) return null
+  const key = fileKey(batchDocAbs)
+  for (const e of getAsyncPool(parent, "subagent")?.values() ?? []) {
+    if (e.status !== "running" && e.status !== "queued") continue
+    if (e.done === true || e.cancelled === true) continue
+    if (!e._batchDoc || fileKey(e._batchDoc) !== key) continue
+    return { id: e.id, role: e.role, status: e.status }
+  }
+  return null
+}
+
+
 /** P-SL2（D-SL2——混合边环形等待停滞机械检测——AGENT-LOOP-SUBAGENT.md §6.9）：
  * 判据（收窄——零误报优先——宁可漏报不可误打断）：池内 running = 0 && queued ≥ 2 &&
  * 无 dependency-cancelled 标记条目 && 每 queued 的 blocker（files 冲突者 + 未 settle