@thincoder/core 0.10.7 → 0.10.8

package/agent-tools/ssh-transport.mjs

@@ -0,0 +1,311 @@
+/**
+ * ssh-transport.mjs — SSH 传输面单点（askpass 链 ∥ 子进程 ∥ 沉降 ∥ 遮蔽 ∥ 输出帽）。
+ * 设计 = `docs/core/design/TOOLS.md` §6.22（D-TO17/D-TO18 · 台账 #1436）。
+ *
+ * 拆档由 = 机制档触 500 顾问线（§6.22 落点表「触 500 顾问线 ⇒ 实施轮先审拆分」）——本档收**运行面**
+ * （与会话语义无关的传输原语），`ssh-session.mjs` 收**会话面**（池 / 生命周期 / 动作）。条目形
+ * （entry）由 `ssh-session.mjs` 定义并持有；本档只经其字段工作（`buf` / `mask` / `_waiters` /
+ * `promptRe` / `state` / `child` / `logStream` / `_notify` / `lastDataAt` / `bytes`）。
+ *
+ * - askpass 链：包装档（Win `.cmd` ∥ POSIX `.sh` 0700）→ `tools/ssh-askpass.mjs` → stdout；秘密只经
+ *   ssh 子进程环境 `TC_SSH_SECRET`（零入参 / 零落盘 / 零回显；环境经 `nodeChildEnv` 单点补 Electron 旗标）。
+ * - 沉降：静默窗 800 ms ∥ 会话提示符正则命中 ⇒ 就绪；硬超时 10 s ⇒ 部分输出 + 可读句（不静默挂起）。
+ * - 遮蔽：写入的秘密对**捕获面与日志面**做字面移除（跨 chunk 切分：保留 `len-1` 尾缓冲）。
+ * - 失败分类族（auth ∥ unreachable ∥ hostkey）照服务端 `src/sandbox/ssh.mjs` 同源判据。
+ * 模块图：→ config.mjs（configDir 缺省）· tools/shared.mjs（解码 ∥ 清洗）· tools/node-child.mjs
+ * （nodeChildEnv）——叶子向、无环（本档不 import `ssh-session.mjs`）。
+ */
+import { chmodSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs"
+import { spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { configDir } from "../config.mjs"
+import { makeDecoder, sanitizeOutput } from "../tools/shared.mjs"
+import { nodeChildEnv } from "../tools/node-child.mjs"
+
+/** 静默窗（§6.22 ③）：到点无新输出 ⇒ 判定就绪。 */
+export const SSH_SETTLE_MS = 800
+/** 硬超时（§6.22 ③/⑥）：到点返回部分输出 + 可读句。 */
+export const SSH_TIMEOUT_MS = 10_000
+/** 单次返回帽（§6.22 ⑥）：保尾 + 截断注记；全量恒在 log。 */
+export const SSH_RETURN_CAP = 8000
+/** 秘密环境变量名（§6.22 ②「秘密传递」行）。 */
+export const SECRET_ENV = "TC_SSH_SECRET"
+/** 内存缓冲保留量（仅覆盖返回帽；全量恒在 log）。 */
+export const BUF_KEEP_CHARS = 64 * 1024
+
+/** 测试缝（单元测试沙箱——生产从不调用；`_setBgTaskLogDirForTest` 同式：一缝管三落点
+ *  （log 目录 ∥ askpass 包装目录 ∥ 预填档）。`prefixArgs` = 夹具替身用（`<node> <夹具脚本> <ssh 参数…>`）。 */
+let _sshBinary = null
+let _sshArgPrefix = []
+let _sshConfigDir = null
+export function _setSshBinaryForTest(cmd, prefixArgs = []) {
+  _sshBinary = cmd
+  _sshArgPrefix = Array.isArray(prefixArgs) ? prefixArgs : []
+}
+export function _setSshConfigDirForTest(dir) { _sshConfigDir = dir }
+export const sshBinary = () => _sshBinary ?? "ssh"
+export const sshArgPrefix = () => _sshArgPrefix
+export const sshConfigDir = () => _sshConfigDir ?? configDir
+
+// ─── askpass 链（包装档 ∥ 环境 ∥ 命令形）────────────────────────────────────
+
+/** 包装档运行期写入（内容零秘密——仅路径；Win `.cmd` ∥ POSIX `.sh` 0700）。 */
+export function writeAskpassWrapper(id) {
+  const dir = `${sshConfigDir()}/ssh-askpass`
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const helper = fileURLToPath(new URL("../tools/ssh-askpass.mjs", import.meta.url))
+  const node = process.execPath
+  const win = process.platform === "win32"
+  const file = `${dir}/askpass-${process.pid}-${id}.${win ? "cmd" : "sh"}`
+  // `.cmd` 首行 `@echo off`：cmd 中介默认回显命令行——回显会占掉 ssh 读回的**首行**
+  // （`readpass.c` 只取首行 ⇒ 口令错位为空串）；POSIX `.sh` 无此面。
+  writeFileSync(file, win ? `@echo off\r\n"${node}" "${helper}" %*\r\n` : `#!/bin/sh\nexec "${node}" "${helper}" "$@"\n`, { mode: 0o700 })
+  try { chmodSync(file, 0o700) } catch { /* win32 无 POSIX mode——尽力面 */ }
+  return file
+}
+
+/** 包装档清理（关闭 / 终结时尽力面——内容零秘密，残留无实害）。 */
+export function unlinkAskpass(entry) {
+  try { if (entry.askpassFile) unlinkSync(entry.askpassFile) } catch { /* 尽力面 */ }
+  entry.askpassFile = null
+}
+
+/** ssh 子进程环境：askpass 链 + 秘密（无秘密时**显式清除**——防父进程残留变量误喂）。 */
+export function buildSshEnv({ wrapper, secret }) {
+  const env = { ...process.env, SSH_ASKPASS: wrapper, SSH_ASKPASS_REQUIRE: "force" }
+  // 占位 DISPLAY：OpenSSH < 8.4 无 `SSH_ASKPASS_REQUIRE`（RHEL 8 / CentOS 8 代）——无 DISPLAY 时
+  // askpass 不被放行（`readpass.c` allow_askpass 判据）；占位后新旧两代同走 askpass（§6.22 NS1 注）。
+  if (!env.DISPLAY) env.DISPLAY = ":0"
+  if (secret != null) env[SECRET_ENV] = secret
+  else delete env[SECRET_ENV]
+  return nodeChildEnv(env)
+}
+
+/** 会话命令形（§6.22 ⑤）：`-tt` 强制远端 PTY + 保活三件 + 单提示；`port`/`user` 未给 ⇒ 不下发。
+ *  预探 = `NumberOfPasswordPrompts=0`（password ∥ keyboard-interactive 两径同被短路——
+ *  `sshconnect2.c` `userauth_passwd` / `userauth_kbdint` 两处同判 `attempt++ >= n`；私钥口令提示
+ *  亦被短路：`load_identity_file` 循环 `i <= number_of_password_prompts`）；带密 = 1（单提示）。 */
+export function buildSshArgs({ host, user, port, probe }) {
+  return [
+    "-tt",
+    "-o", "ConnectTimeout=10",
+    "-o", "ServerAliveInterval=30",
+    "-o", "ServerAliveCountMax=4",
+    "-o", `NumberOfPasswordPrompts=${probe ? 0 : 1}`,
+    ...(port ? ["-p", String(port)] : []),
+    user ? `${user}@${host}` : host,
+  ]
+}
+
+// ─── 遮蔽（§6.22 ⑦）────────────────────────────────────────────────────────
+
+/** 秘密遮蔽过滤器：字面移除 + `len-1` 尾缓冲（跨 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)
+    },
+    push(text) {
+      let out = tail + String(text ?? "")
+      for (const s of secrets) out = out.split(s).join("")
+      if (out.length <= keep) { tail = out; return "" }
+      const emit = out.slice(0, out.length - keep)
+      tail = out.slice(out.length - keep)
+      return emit
+    },
+    /** 沉降时冲涮尾缓冲：**只放行非秘密前缀段**（尾内最长可疑后缀一律扣下——整尾 ∥ 移位前缀
+     *  都不出返回面；扣下的至多 `秘密长-1` 字符，代价 < 前缀外泄）。 */
+    flush() {
+      const t = tail
+      tail = ""
+      if (!t) return ""
+      let cut = 0
+      for (const s of secrets) {
+        const max = Math.min(t.length, s.length - 1)
+        for (let L = 1; L <= max; L++) if (t.endsWith(s.slice(0, L))) cut = Math.max(cut, L)
+      }
+      return cut ? t.slice(0, t.length - cut) : t
+    },
+  }
+}
+
+// ─── 子进程（起跑 ∥ 双流汇入 ∥ 退出）────────────────────────────────────────
+
+/** 悬挂 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) {
+    entry.buf = entry.buf.slice(entry.buf.length - BUF_KEEP_CHARS)
+    entry.bufDropped = true
+  }
+  entry._notify?.(text)
+  entry.lastDataAt = Date.now()
+  for (const w of [...entry._waiters]) w("data")
+}
+
+/** 子进程挂载（双流解码 ∥ 退出 ∥ spawn 错误——探连与会话同径）。 */
+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 flush = () => {
+    const rest = sanitizeOutput(outDecoder(Buffer.alloc(0), true)) + sanitizeOutput(errDecoder(Buffer.alloc(0), true))
+    if (rest) feed(Buffer.from(rest, "utf8"))
+  }
+  child.stdout.on("data", (d) => feed(outDecoder(d)))
+  child.stderr.on("data", (d) => feed(errDecoder(d)))
+  // stdin 无 error 监听 ⇒ 对端刚死时写入的异步 EPIPE 会以未处理 'error' 事件逸出（uncaughtException）。
+  // 同族先例：CLI `tui/clipboard.mjs` ∥ `mcp/transport-stdio.mjs` 同式吞 EPIPE。
+  child.stdin?.on("error", () => { /* 写失败由 send ∥ secret_input 的调用面回读；此处仅防未处理事件 */ })
+  child.on("error", (error) => {
+    if (entry.child !== child) return // 旧进程（已被重起替换）——判定面不采
+    entry.spawnError = error?.message ?? String(error)
+    for (const w of [...entry._waiters]) w("exit")
+  })
+  child.on("exit", (code, exitSignal) => {
+    if (entry.child !== child) return // 旧进程（探连 → 带密会话的重起面）——事件不污染新连接判定
+    entry.exitInfo = { code, signal: exitSignal }
+    flush()
+    // 已就绪（会话态）⇒ 远端断开：终态 + 墓碑（E5）；探连期的退出由 connect 判定径处置（不在此收尾）。
+    if (entry.state === "ready" && entry.closing !== true) entry.onRemoteExit?.(entry)
+    for (const w of [...entry._waiters]) w("exit")
+  })
+}
+
+/** 起跑一条 ssh（探连 ∥ 带密会话同径）。重起（探连 → 带密会话）⇒ 判定面复位：exitInfo ∥
+ *  spawnError 属**上一次**进程（残留会让新连接的成功判定被误读成「已退出」）。 */
+export function spawnSession(entry, { user, port, secret }) {
+  entry.exitInfo = null
+  entry.spawnError = null
+  const child = spawn(sshBinary(), [...sshArgPrefix(), ...buildSshArgs({ host: entry.host, user, port, probe: secret == null })], {
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+    detached: process.platform !== "win32",
+    env: buildSshEnv({ wrapper: entry.askpassFile, secret }),
+  })
+  attachChild(entry, child)
+  return child
+}
+
+// ─── 沉降（§6.22 ③）────────────────────────────────────────────────────────
+
+function promptHit(entry) {
+  return Boolean(entry.promptRe && entry.promptRe.test(entry.buf))
+}
+
+/** 等到「就绪判据」成立：提示符命中 ∥ 静默窗到点 ∥ 硬超时 ∥ 退出 ∥ 中止（返回 reason）。 */
+export function waitSettled(entry, { timeoutMs = SSH_TIMEOUT_MS, signal = null } = {}) {
+  return new Promise((resolve) => {
+    let done = false
+    let quietTimer = null
+    const deadline = Date.now() + Math.max(1, Number(timeoutMs) || SSH_TIMEOUT_MS)
+    const finish = (reason) => {
+      if (done) return
+      done = true
+      clearTimeout(quietTimer)
+      clearTimeout(deadlineTimer)
+      signal?.removeEventListener("abort", onAbort)
+      entry._waiters.delete(onEvent)
+      resolve(reason)
+    }
+    const arm = () => {
+      clearTimeout(quietTimer)
+      quietTimer = setTimeout(() => finish(promptHit(entry) ? "prompt" : "silence"), SSH_SETTLE_MS)
+    }
+    const onEvent = (kind) => {
+      if (kind === "exit") return finish("exited")
+      if (promptHit(entry)) return finish("prompt")
+      arm()
+    }
+    const onAbort = () => finish("aborted")
+    const deadlineTimer = setTimeout(() => finish("timeout"), Math.max(0, deadline - Date.now()))
+    if (entry.state === "dead" || entry.state === "closed") return finish("exited")
+    if (signal?.aborted) return finish("aborted")
+    signal?.addEventListener("abort", onAbort, { once: true })
+    entry._waiters.add(onEvent)
+    onEvent("data") // 起点：先查提示符，否则起静默窗（「send 后 800 ms 无新输出」从本刻起算）
+  })
+}
+
+/** 就绪结论注记（§6.22 ③：静默 ∥ 提示符 ∥ 超时——超时带 id / host / 已等时长，不静默挂起）。 */
+export function settleNote(entry, reason, waitedMs) {
+  if (reason === "prompt") return "settled (prompt matched)"
+  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 === "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)
+}
+
+// ─── 输出面（缓冲 ∥ 帽 ∥ 状态行）────────────────────────────────────────────
+
+export const idLabel = (entry) => `ssh#${entry.id}`
+
+/** 取出未读输出（遮蔽尾缓冲先冲涮）。 */
+export function drain(entry) {
+  const flushed = entry.mask.flush()
+  if (flushed) entry.buf += flushed
+  const text = entry.buf
+  entry.buf = ""
+  const dropped = entry.bufDropped === true
+  entry.bufDropped = false
+  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 动作表末行）：每返回首行。 */
+export function statusLine(entry) {
+  const idle = Math.max(0, Math.round((Date.now() - entry.lastActivityAt) / 1000))
+  return `[ssh (${idLabel(entry)}) ${entry.host} — ${entry.state} · idle ${idle}s]`
+}
+
+/** 体形（空 ⇒ `(no output)`；非空转义——`bash-async.mjs renderDigest` 同式）。 */
+export function bodyText(text) {
+  return text.trim() ? escapeXmlLite(text.replace(/\s+$/u, "")) : "(no output)"
+}
+
+/** XML 转义（`agent/helpers.mjs escapeXml` 同式；本档为零依赖注入面自持小实现，避免
+ *  transport → agent 反向依赖）。 */
+function escapeXmlLite(s) {
+  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;")
+}
+
+// ─── 失败分类（照服务端分类族：auth ∥ unreachable ∥ fingerprint_changed）─────
+
+export function classifyFailure(stderr) {
+  const text = String(stderr ?? "")
+  if (/REMOTE HOST IDENTIFICATION HAS CHANGED|Host key verification failed|host key .* revoked|requested strict checking/i.test(text)) {
+    return { kind: "hostkey", message: "host key verification failed — the key changed or your local ssh config requires strict checking; known_hosts is never rewritten by this tool" }
+  }
+  if (/Permission denied|Too many authentication failures|Authentication failed/i.test(text)) {
+    return { kind: "auth", message: "authentication rejected" }
+  }
+  if (/Connection timed out|Connection refused|No route to host|Could not resolve hostname|Connection closed by|Network is unreachable|connect to host .* failure/i.test(text)) {
+    return { kind: "unreachable", message: "host unreachable or timed out" }
+  }
+  return null
+}
+
+/** 失败句（含 id ∥ host；尾附探测现场末段——诊断面）。 */
+export function failureText(entry, cls, extra = "") {
+  const at = `(${idLabel(entry)} @ ${entry.host})`
+  const tail = entry.buf.trim() ? `\n${escapeXmlLite(entry.buf.trim().slice(-600))}` : ""
+  return `Error: ssh ${cls ? cls.message : "connection failed"} ${at}${extra}${tail}`
+}

package/agent-tools/subagent-scheduler.mjs

@@ -43,7 +43,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）：黑名单随同迁入 spawn-gates.mjs（rejectEngineeringFilePaths——族 = ledger.db / CHANGELOG + scripts/**；老台账 md 族随 M2 退役）——本函数只留调用（错误文案逐字保留）。 */
+ *  M5 F6（2026-09-17——2026-10-15 口径随正）：黑名单随同迁入 spawn-gates.mjs（rejectEngineeringFilePaths——族 = 过程档（CHANGELOG）+ 工程工具面（`scripts/*`——层级锚定：仅仓根与直接子层；目录名在深层不携带 face 信息）；老台账 md 族随 M2 退役）——本函数只留调用（错误文案逐字保留）。 */
 export function normalizeFileList(files, cwd) {
   const out = []
   for (const f of Array.isArray(files) ? files : []) {
@@ -57,10 +57,10 @@ export function normalizeFileList(files, cwd) {
     }
     if (!out.includes(abs)) out.push(abs)
   }
-  // M5 F6（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：scripts/** + 过程档拦截——
+  // M5 F6（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2——2026-10-15 口径随正）：`scripts/*`（仅仓根/直接子层）+ 过程档拦截——
   // 谓词本体落 spawn-gates.mjs（rejectEngineeringFilePaths 收集全部违规 + 抛合并错误）；
   // 循环内目录声明先行（错误序不变——目录错误先于过程档错误）。父侧维护文件
-  // basename 族（ledger.db / CHANGELOG）随同迁入谓词——错误文案逐字保留。
+  // basename 族（CHANGELOG——`ledger.db` 随 M2 退役）随同迁入谓词——错误文案逐字保留。
   if (files !== undefined && files !== null) rejectEngineeringFilePaths(files)
   return out
 }
@@ -398,14 +398,15 @@ export function maybeRefillAsync(parent) {
  * spawn（subagent-spawn.mjs async 分支）、escalate（escalate-async.mjs）、async-advisor
  * 池（advisor-async.mjs——§6.10 跨池共号）、**后台 bash 任务池**（bash-async.mjs——#9：
  * `_bgTasks` 同入扫描域——VSC 形计数器不随 run 存活，缺此扫描会与在途 bg 条目撞号）、
- * **后台浏览器动作池**（browser-async.mjs——批 browser-async-fix：`_browserTasks` 同入）共用；
+ * **后台浏览器动作池**（browser-async.mjs——批 browser-async-fix：`_browserTasks` 同入）、
+ * **SSH 会话池**（ssh-session.mjs——批 ssh-session：`_sshSessions` 同入——同因）共用；
  * executeAsyncSpawn 直读 counter（分配与
  * 消费同步——无 await 间隙）。CLI 两池键均为字符串（set(String(id))——解析分支防御保留）。
  * @returns {number} 全池唯一的下一 id（单调——进程内）
  */
 export function nextSubagentId(parent) {
   let poolMax = 0
-  for (const pool of [carrierField(parent, "_asyncSubagents"), carrierField(parent, "_asyncAdvisors"), carrierField(parent, "_bgTasks"), carrierField(parent, "_browserTasks")]) {
+  for (const pool of [carrierField(parent, "_asyncSubagents"), carrierField(parent, "_asyncAdvisors"), carrierField(parent, "_bgTasks"), carrierField(parent, "_browserTasks"), carrierField(parent, "_sshSessions")]) {
     if (!pool || pool.size === 0) continue
     for (const k of pool.keys()) {
       const n = typeof k === "number" ? k : Number.parseInt(k, 10)

package/agent-tools/subagent.mjs

@@ -3,8 +3,9 @@
  * 2026-09-07 token 链终消费制：+action: consume-design（ENGINEERING-MODE.md §2.6 F1——
  * 父侧链终核销消费 designId 槽——执行器 executeConsumeDesignAction 在 subagent-spawn.mjs）。
  * 2026-10-07 批 ledger-tool（#927 并入）：+action: design-slots（只读清点面——
- * DESIGN-TOKEN-SETTLEMENT.md §10 F-SL1）+ consume-design 选择器扩展（designIds / expired /
+ * DESIGN-TOKEN-SETTLEMENT.md §9 F-SL1）+ consume-design 选择器扩展（designIds / expired /
  * olderThanDays）——实现在 `design-slots.mjs`（subagent-spawn.mjs re-export 保 import 面）。
+ * 2026-10-14 批 design-token-recovery（#1384 并入）：design-slots 回收读口——`designId` 过滤 + `reveal:true` 单槽揭值（必携 designId；掩蔽 = 只揭活槽）——实现随动在 `design-slots.mjs`。
  *
  * 2026-09-03 拆分轮: subagent.mjs 超 500 硬顶——async 常量、共享 post-spawn 管线
  *（runChildPipeline）与队列/注入/并账机械迁至 ./subagent-async.mjs。execute
@@ -114,8 +115,8 @@ export function buildSyncStoppedReport(role, capturedOutput, designId) {
  * a stronger model) / cancel (stop ONE background subagent — AGENT-LOOP-SUBAGENT.md §6.7.2) / panel (view + fix
  * the live subagent panel — AGENT-LOOP-SUBAGENT.md §6.7.2) / consume-design (parent-side chain-terminal token
  * consumption — ENGINEERING-MODE.md §2.6, 2026-09-07; selectors designId / designIds / expired /
- * olderThanDays — DESIGN-TOKEN-SETTLEMENT.md §10 F-SL2) / design-slots (read-only slot inventory —
- * DESIGN-TOKEN-SETTLEMENT.md §10 F-SL1, 2026-10-07). The check
+ * olderThanDays — DESIGN-TOKEN-SETTLEMENT.md §9 F-SL2) / design-slots (read-only slot inventory —
+ * DESIGN-TOKEN-SETTLEMENT.md §9 F-SL1, 2026-10-07). The check
  * action was deleted (AGENT-LOOP-SUBAGENT.md §6.7.5): async results reach the model only via the auto channel.
  * - action:"spawn" roles: "explore" — read-only tools, search/read/analyze
  *   (suitable for codebase exploration); "coder" — full tool set, self-contained
@@ -144,10 +145,11 @@ export const subagentTool = {
       role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder", "eng-designer"], description: "The sub-agent role — see the role matrix in the tool description. Exact spelling required. action:'spawn' only (escalate spawns its own expert internally)." },
       model: { type: "string", description: "action:'spawn': provider/model override ('provider:model', a provider, or a model name on the parent's provider) — defaults config.agent.subagentModels[role] → config.agent.subagentModel → the parent's provider; \"default\" inherits. action:'escalate': a consult candidate (default = the first)." },
       designToken: { type: "string", description: "Required when role='eng-coder': the token from advisor(type='design') after the review passed — without it, eng-coder cannot modify files." },
-      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the single-slot selector (required to pick between several; the gate refuses to guess); see designIds / expired / olderThanDays for batch consumption." },
+      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the single-slot selector (required to pick between several; the gate refuses to guess); see designIds / expired / olderThanDays for batch consumption. action:'design-slots': filter the inventory to one slot (trimmed exact match; an empty string means no filter; an unknown id is refused with the held id list) — REQUIRED with reveal:true." },
       designIds: { type: "array", items: { type: "string" }, description: "action:'consume-design' (batch): an explicit non-empty list of design ids to close out — pass exactly ONE selector per call (designId / designIds / expired / olderThanDays)." },
       expired: { type: "boolean", description: "action:'consume-design' (batch): true = close out every expired slot (exactly ONE selector per call)." },
       olderThanDays: { type: "number", description: "action:'consume-design' (batch): close out every slot older than N days (age > N; exactly ONE selector per call)." },
+      reveal: { type: "boolean", description: "action:'design-slots' only: true = reveal the selected slot's full designToken — REQUIRES designId (one slot at a time, never a bulk dump); an expired or malformed slot is masked (designToken=—); a non-boolean value is refused. After a token drops from your context (compaction, restart), read it back this way and pass designId + designToken verbatim on the eng-coder spawn — the gate checks exact equality." },
       batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (e.g. <repo>/docs/batches/<batch>-<topic>.md; relative paths resolve against the session cwd first, then candidate project roots — or absolute) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated. role='coder' (normal mode): optional — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file." },
       round: { type: "string", enum: ROUND_VALUES, description: "REQUIRED for role='eng-coder'/'eng-designer': initial (first round for this design) or fix (a correction round reusing the same designId+designToken; docs FIRST). No default — missing = refused." },
       async: { type: "boolean", description: "action:'spawn'/'escalate': default at depth 0 = true (async; the report arrives automatically); depth>0 always sync. async:false forces the blocking flight." },
@@ -192,7 +194,7 @@ export const subagentTool = {
       // 非只读控制动作——depth-0 + 工程模式限定（本分流已过受限变体门；工程模式门在
       // 执行器内）——planMode 拒绝（dispatch 不豁免）——不入批审批分组（dispatch 免审）。
       if (action === "consume-design") return executeConsumeDesignAction(args, ctx)
-      // 2026-10-07 批 ledger-tool（#927 并入——DESIGN-TOKEN-SETTLEMENT.md §10 F-SL1）：design-slots =
+      // 2026-10-07 批 ledger-tool（#927 并入——DESIGN-TOKEN-SETTLEMENT.md §9 F-SL1）：design-slots =
       // 只读清点（工程模式父侧限定——门在执行器内）；dispatch 分类 = readonly（planMode 放行 /
       // 免审批 / digest 放行——同 status / observe）。
       if (action === "design-slots") return executeDesignSlotsAction(args, ctx)

package/agent-tools/task.mjs

@@ -51,7 +51,7 @@ export const taskTool = {
   },
   readonly: true,
   async execute(args, ctx) {
-    // F10（工程模式机械停用——双层门的 **execute 层兜底**；先例 = escalate `subagent-actions.mjs:349`）：
+    // F10（工程模式机械停用——双层门的 **execute 层兜底**；先例 = escalate `subagent-actions.mjs` 的 `executeEscalateAction`）：
     // 前置位 = 本行以下全部副作用之前（alias 归一 / `_taskPushbacks` 归零 / `_onTaskUpdate` / 轻推）
     // ⇒ 零副作用（列表不变）；装配层已摘（`agent/family-tools.mjs` 工程分支不入表，KD8）。
     // 普通模式（engineering 非真）逐字走原路径。

package/agent-tools/timer.mjs

@@ -135,6 +135,12 @@ export const timerTool = {
     const hasDaily = args.daily !== undefined && args.daily !== null
     const hasCancel = args.cancel !== undefined && args.cancel !== null
     const wantsList = args.list === true
+    // `list` 键在场须恰为 `true`——否则显式拒（防 `{list:false}` 静默落缺省 180s：无义键触发真实副作用）。
+    if (args.list !== undefined && args.list !== null && args.list !== true) {
+      throw new Error(
+        `timer: list accepts only true (got: ${String(args.list)}) — omit list to set a timer; pass { list: true } to list pending timers`,
+      )
+    }
     const forms = [hasSeconds && "seconds", hasAt && "at", hasEvery && "every", hasDaily && "daily"].filter((v) => v !== false)
     if (forms.length > 1 || (forms.length > 0 && (hasCancel || wantsList)) || (hasCancel && wantsList)) {
       const given = [...forms, hasCancel && "cancel", wantsList && "list"].filter((v) => v !== false).join(" / ")

package/agent-tools/zero-write-watch.mjs

@@ -22,12 +22,12 @@ const WATCH_ROLES = new Set(["eng-coder", "eng-designer"])
 
 /** 子代理族文案（§6.32.4 逐字——父侧定稿；`from` = `_upstream.label`，形 `role#id`）。 */
 export function zeroWriteAlertText(from, rounds) {
-  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no file write — take a look (subagent action:'status' for the live view).`
+  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no file write — check for a non-writing loop: inspect (subagent action:'observe'), then steer or cancel.`
 }
 
 /** 评审族文案（§6.32.4 逐字——父侧定稿；`from` = `advisor#<entry id>`）。 */
 export function advisorAlertText(from, rounds) {
-  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no review output — take a look (subagent action:'status' / 'cancel').`
+  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no review output — check for a stalled review: inspect (subagent action:'status'), then cancel.`
 }
 
 /**

package/agent-tools.mjs

@@ -22,9 +22,10 @@ export { batchTool } from "./agent-tools/batch.mjs"
 // 批次档生命周期工具（BATCH-RECORD §4.3 挂载表——主名 `batch` 单工具四 action：depth-0 主 agent
 // create/close + append/status 域随模式（工程面 = append §1/§4/§6 ∥ status §1；普通面 = append §1/§2/§4/§5/§6 ∥ status §1/§2/§5）（轮 2 裁定②：§4/§6 状态面走普通文档写）（D-BR18）；
 // eng 子代理 eng 分支绑定段写入；评审 §3。
-// CORE-UNIFICATION TOOLS #83（统一登记册——VSC `agent-tools/index.mjs:15` 含 consult 家族；
-// CLI 原把 consult 另挂 `agent/setup.mjs:173` ⇒ 归位：登记册即单一来源，装配方只读本档）。
+// CORE-UNIFICATION TOOLS #83（统一登记册——VSC `agent-tools/index.mjs` 含 consult 家族；
+// CLI 原把 consult 另挂 `agent/setup.mjs` 的家族段装配 ⇒ 归位：登记册即单一来源，装配方只读本档）。
 export { consultStartTool, consultStopTool } from "./agent-tools/consult.mjs"
 // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 装配接线）：子代理上行通道工具
 // （depth>0 段装配——`agent/family-tools.mjs`；depth-0 / consult 不装配）。
 export { parentChannelTool } from "./agent-tools/parent-channel.mjs"
+export { docCheckTool } from "./agent-tools/doc-check.mjs" // 文档纪律机检（DOC-DISCIPLINE.md §3.20 条目 S——产品内建 · 报告态 · 非门禁）

package/attachments.mjs

@@ -5,9 +5,9 @@
  * 上提源（迁移前坐标）= VSC `thincoder-vscode/src/extension/image-handler.mjs`（`parseDataUrl` :34 ·
  * `savePastedImages` :49 · `downgradeNonVisionImages` :109）；预算语义（合计 30MB ∕ 轮 · 溢出项弃后
  * **继续扫**「其余照发」）与配额单位 = 桌面同档 `thincoder-desktop/src/main/attachments.mjs`
- * （15MB ∕ 条 —— 与核 `read_image` 内闸同值同单位：`tools/file.mjs:26` `MAX_IMAGE_BYTES = 15_000_000`，
+ * （15MB ∕ 条 —— 与核 `read_image` 内闸同值同单位：`tools/file.mjs` `MAX_IMAGE_BYTES = 15_000_000`，
  * 接纳面不得宽于该闸）。本档 = 单源（消费面 = 桌面 `src/main/attachments.mjs`；VSC 自持副本已随本批（parity-b4）迁移改指本档）。
- * 指引行（`[Attached images: …]`）不迁 —— 单源 = `agent/setup-reminders.mjs:248` `appendImagePointer`（原位）。
+ * 指引行（`[Attached images: …]`）不迁 —— 单源 = `agent/setup-reminders.mjs` `appendImagePointer`（原位）。
  *
  * 与 VSC 自持副本的在册差异（双写窗口）**收正已毕**（迁移轮 parity-b4 —— 逐条处置见批档 §2.3）：① 阈单位 ∕
  * ② 弃项索引 ∕ ③ 合计预算闸 ∕ ④ 降级成功判据 = **两端同源单值**（收正方向——VSC 侧本地字面 ∕ 过滤后下标 ∕ 无预算 ∕
@@ -28,7 +28,7 @@
 import { join } from "node:path"
 import { specForModel } from "./model-specs.mjs"
 
-/** 单项上限 15MB（与 `read_image` 内闸同值同单位 —— `tools/file.mjs:26` `MAX_IMAGE_BYTES = 15_000_000`：
+/** 单项上限 15MB（与 `read_image` 内闸同值同单位 —— `tools/file.mjs` `MAX_IMAGE_BYTES = 15_000_000`：
  *  超阈件交核也读不进 ⇒ 接纳面不得宽于该闸）。 */
 export const IMAGE_MAX_BYTES = 15_000_000
 
@@ -73,7 +73,7 @@ export function savePastedImages(dataUrls, cwd, { fs } = {}) {
     return { paths: [], dropped: list.length }
   }
   const tmpDir = join(cwd, ".thincoder", "tmp")
-  const runId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6) // 命名先例 = image-handler.mjs:56
+  const runId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6) // 命名先例 = `image-handler.mjs` 的 `downgradeNonVisionImages`
   const paths = []
   let dropped = 0
   let budget = TURN_MAX_BYTES

package/browser/cdp.mjs

@@ -1,7 +1,7 @@
 /**
  * browser/cdp.mjs — CDP 传输客户端（零第三方——N-BT1：Node ≥ 24 原生 WebSocket）。
  *
- * 形沿 `scripts/console-walkthrough.mjs:133-141` 的实证客户端（id 派发 ∥ 事件派发）——本文档把它
+ * 形沿 `scripts/console-walkthrough.mjs` 的实证客户端（id 派发 ∥ 事件派发）——本文档把它
  * 拆成类以承载多动作会话（connect / call / on / close），并加 HTTP 面 `/json/new` 取标签页。
  * `WebSocketImpl` = 注入缝（缺省 `globalThis.WebSocket`；单元测试注假传输——缺省回落真实现，`??`）。
  *
@@ -135,7 +135,7 @@ export async function connectCdp(wsUrl, { WebSocketImpl, openTimeoutMs = CONNECT
   return new CdpClient(ws)
 }
 
-/** 开一张标签页并取其调试地址（`PUT /json/new`，GET 兜底——walkthrough `:131-132` 同式；fetch 帽 5s）。 */
+/** 开一张标签页并取其调试地址（`PUT /json/new`，GET 兜底——walkthrough 同式；fetch 帽 5s）。 */
 export async function newTabWebSocketUrl(port, { host = "127.0.0.1", fetchImpl = globalThis.fetch, timeoutMs = NEWTAB_TIMEOUT_MS } = {}) {
   const url = `http://${host}:${port}/json/new?about:blank`
   let timer = null

package/browser/launch.mjs

@@ -1,10 +1,10 @@
 /**
  * browser/launch.mjs — 浏览器发现 ∥ profile 锁 ∥ 启动 ∥ 杀树（BROWSER-TOOL.md §4）。
  *
- * 候选表与启动参数沿 `scripts/console-walkthrough.mjs:33-44`（Edge 先于 Chrome）∥ `:123`
+ * 候选表与启动参数沿 `scripts/console-walkthrough.mjs`（Edge 先于 Chrome）∥ 同档启动参数段
  * （`--headless=new` ∥ `--remote-debugging-port=0` ∥ `stdio:"ignore"` ∥ POSIX `detached`）——
  * 本档不 import 该脚本，只内化其形。
- * profile = `~/.thincoder/browser/profile`（`configDir` 同源——`config-io.mjs:32`）= **持久**
+ * profile = `~/.thincoder/browser/profile`（`configDir` 同源——`config-io.mjs`）= **持久**
  * （F-BT6：有头登录一次 ⇒ 后续含无头复用登录态）。
  *
  * 注入缝（N-BT6）：`resolveBrowser({platform, env, pathExists, which})` 与 `acquireProfileLock`
@@ -96,12 +96,56 @@ export function releaseProfileLock(lockPath, io = {}) {
   removeText(lockPath)
 }
 
+/** 同 profile 残留进程列表（平台分支——一次 exec 取全表；失败 ⇒ []——尽力面零抛）：win32 = 一次
+ *  Get-CimInstance（PowerShell——wmic 已从新系统移除）；POSIX = 一次 ps（自持列表面：既有
+ *  `process-probe-exec.mjs` 那条链按已知 pid 查 cmdline，本面是反查——零第三方依赖）。 */
+function defaultListProfileProcs(platform = process.platform) {
+  try {
+    if (platform === "win32") {
+      const out = execFileSync("powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-Command",
+          "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"],
+        { encoding: "utf8", timeout: 15_000, stdio: ["ignore", "pipe", "ignore"] })
+      const rows = JSON.parse(out.trim() || "[]")
+      return (Array.isArray(rows) ? rows : [rows]).filter((r) => r && Number.isInteger(r.ProcessId)).map((r) => ({ pid: Number(r.ProcessId), cmdline: r.CommandLine ?? "" }))
+    }
+    const out = execFileSync("ps", ["-eo", "pid=,args="], { encoding: "utf8", timeout: 15_000, stdio: ["ignore", "pipe", "ignore"] })
+    return out.split(/\r?\n/).map((l) => l.match(/^\s*(\d+)\s+(.*)$/)).filter(Boolean).map((m) => ({ pid: Number(m[1]), cmdline: m[2] }))
+  } catch { return [] }
+}
+
+/** 同 `--user-data-dir` 残留浏览器进程树回收（#1304——启动序在 spawn 前调用）：陈旧实例占住
+ *  profile ⇒ 新实例自退 + `DevToolsActivePort` 永不落盘 = 起不动；回收后再 spawn。
+ *  锁空闲判据同 `acquireProfileLock`（活 pid 持•非本进程 ⇒ 不回收——既有错由 acquire 支照抛）；
+ *  `io` = 注入缝（`platform` ∥ `readText`/`isAlive`/`pid` ∥ `list` ⇒ [{pid, cmdline}] ∥ `kill(pid)`）；
+ *  平台分支 + 尽力面零抛（列表 ∥ 单杀失败均不阻断启动）；`close` 路径既有杀树（`killBrowser`）零改
+ *  ——默认杀器即复用它（pid 形）。 */
+export function reclaimProfileOrphans(profile, io = {}) {
+  try {
+    const platform = io.platform ?? process.platform
+    const readText = io.readText ?? ((p) => { try { return readFileSync(p, "utf8") } catch { return "" } })
+    const isAlive = io.isAlive ?? defaultPidAlive
+    const pid = io.pid ?? process.pid
+    const held = Number(String(readText(join(dirname(profile), "session.lock")) ?? "").trim())
+    if (Number.isInteger(held) && held > 0 && held !== pid && isAlive(held)) return // 锁被活 pid 持 ⇒ 不回收
+    const list = io.list ?? (() => defaultListProfileProcs(platform))
+    const kill = io.kill ?? ((target) => killBrowser({ pid: target, kill: (signal) => process.kill(target, signal) }, { platform }))
+    const marker = `--user-data-dir=${profile}`
+    for (const row of list() ?? []) {
+      const target = Number(row?.pid)
+      if (!Number.isInteger(target) || target <= 0 || target === pid) continue
+      if (!String(row?.cmdline ?? "").replace(/"/g, "").includes(marker)) continue
+      try { kill(target) } catch { /* 单条失败不阻断其余 */ }
+    }
+  } catch { /* 回收失败不阻断启动（尽力面零抛） */ }
+}
+
 /**
  * 启动浏览器（spawn + `DevToolsActivePort` 轮询 ≤12s）。
  * 持久 profile ⇒ 启动前清陈旧端口文件（否则旧值被当本次读数——发现即失效）。
  * @returns {Promise<{child: import("node:child_process").ChildProcess, port: number, profile: string}>}
  */
-export async function launchBrowser({ exe, headless = true, profile, timeoutMs = START_TIMEOUT_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+export async function launchBrowser({ exe, headless = true, profile, timeoutMs = START_TIMEOUT_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), reclaimIo = undefined } = {}) {
   const args = [
     ...(headless ? ["--headless=new"] : []),
     "--disable-gpu", "--no-first-run", "--hide-scrollbars",
@@ -109,6 +153,8 @@ export async function launchBrowser({ exe, headless = true, profile, timeoutMs =
     "--window-size=1440,900", "about:blank",
   ]
   mkdirSync(profile, { recursive: true })
+  // #1304：锁空闲（调用序保证——`acquireProfileLock` 在前）⇒ 先回收同 profile 残留进程树，再 spawn。
+  reclaimProfileOrphans(profile, reclaimIo)
   const portFile = join(profile, "DevToolsActivePort")
   rmSync(portFile, { force: true })
   const child = spawn(exe, args, { stdio: "ignore", detached: process.platform !== "win32" })
@@ -131,7 +177,7 @@ export async function launchBrowser({ exe, headless = true, profile, timeoutMs =
   return { child, port, profile }
 }
 
-/** 杀整棵进程树（win32 `taskkill /T /F`；POSIX 组杀 + 单杀兜底——walkthrough `:192-193` 同式）。 */
+/** 杀整棵进程树（win32 `taskkill /T /F`；POSIX 组杀 + 单杀兜底——walkthrough 同式）。 */
 export function killBrowser(child, { platform = process.platform, exec = execFileSync } = {}) {
   if (!child || typeof child.pid !== "number") return
   if (platform === "win32") {

package/browser/snapshot.mjs

@@ -263,7 +263,7 @@ export function renderSnapshot({ url, title, rows = [], total = rows.length }) {
   return truncateText(lines.join("\n"), MAX_SNAPSHOT_CHARS, "pass selector to narrow")
 }
 
-/** 截断（`truncate` 同款标记形态——`tools/shared.mjs:190-193`）。 */
+/** 截断（`truncate` 同款标记形态——`tools/shared.mjs`）。 */
 export function truncateText(text, max, note = "narrow the request") {
   if (text.length <= max) return text
   return `${text.slice(0, max)}\n[... truncated: ${text.length - max} chars omitted — ${note}]`

package/config-io.mjs

@@ -197,8 +197,11 @@ export function cascadeRemoveProvider(raw, name) {
 
 // ─── Provider 持久化面（§2.5 #177「纯持久化函数取一侧 + UI 壳按端注入」）───
 
-/** 写一个渠道的 key（整 providers[] 重写）。冲突 → CONFIG_CONFLICT_HINT；成功 null。 */
+/** 写一个渠道的 key（整 providers[] 重写）。渠道不在册 ⇒ `Provider "<name>" not found`（零写——#1179 假成功收正）；
+ *  冲突 → CONFIG_CONFLICT_HINT；成功 null。 */
 export function setProviderKey(name, key) {
+  const existing = loadRaw()
+  if (!Array.isArray(existing.providers) || !existing.providers.some((p) => p && p.name === name)) return `Provider "${name}" not found`
   const r = persistRaw((raw) => {
     raw.providers = Array.isArray(raw.providers) ? raw.providers : []
     const entry = raw.providers.find((p) => p?.name === name)
@@ -207,8 +210,10 @@ export function setProviderKey(name, key) {
   return conflictError(r)
 }
 
-/** 移除一个渠道的 key（保留渠道条目）。冲突提示同 setProviderKey。 */
+/** 移除一个渠道的 key（保留渠道条目）。渠道不在册 ⇒ `Provider "<name>" not found`（零写——#1179）；冲突提示同 setProviderKey。 */
 export function removeProviderKeyFromConfig(name) {
+  const existing = loadRaw()
+  if (!Array.isArray(existing.providers) || !existing.providers.some((p) => p && p.name === name)) return `Provider "${name}" not found`
   const r = persistRaw((raw) => {
     const entry = Array.isArray(raw.providers) ? raw.providers.find((p) => p?.name === name) : null
     if (entry) delete entry.apiKey