@thincoder/core 0.10.7 → 0.10.9

package/agent-tools/ssh-transport.mjs

@@ -0,0 +1,324 @@
+/**
+ * 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 { homedir } from "node:os"
+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 ④：`ServerAliveInterval=30`；测试态时间缝按 ms 传入后换算）。 */
+export const SSH_KEEPALIVE_MS = 30_000
+/** 秘密环境变量名（§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)
+}
+
+/** `~` 展开（`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 两径同被短路——
+ *  `sshconnect2.c` `userauth_passwd` / `userauth_kbdint` 两处同判 `attempt++ >= n`；私钥口令提示
+ *  亦被短路：`load_identity_file` 循环 `i <= number_of_password_prompts`）；带密 = 1（单提示）。 */
+export function buildSshArgs({ host, user, port, probe, identityFile = null, keepAliveMs = SSH_KEEPALIVE_MS }) {
+  const keepAliveS = Math.max(1, Math.round((Number(keepAliveMs) || SSH_KEEPALIVE_MS) / 1000))
+  return [
+    "-tt",
+    "-o", "ConnectTimeout=10",
+    "-o", `ServerAliveInterval=${keepAliveS}`,
+    "-o", "ServerAliveCountMax=4",
+    "-o", `NumberOfPasswordPrompts=${probe ? 0 : 1}`,
+    ...(port ? ["-p", String(port)] : []),
+    ...(identityFile ? ["-i", expandHome(identityFile)] : []),
+    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, identityFile = null, keepAliveMs = SSH_KEEPALIVE_MS }) {
+  entry.exitInfo = null
+  entry.spawnError = null
+  const child = spawn(sshBinary(), [...sshArgPrefix(), ...buildSshArgs({ host: entry.host, user, port, probe: secret == null, identityFile, keepAliveMs })], {
+    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/ssh-vault.mjs

@@ -0,0 +1,291 @@
+/**
+ * ssh-vault.mjs — SSH 保存凭据单点（保存件读写 ∥ 系统级加密后端 ∥ 清单 / 删除 ∥ 可用性判定 ∥ 凭据窗获取链）。
+ * 设计 = `docs/core/design/TOOLS.md` §6.22 ⑪（D-TO19 · 用户裁定 A+B）；台账 #1602。
+ *
+ * 档：`configDir/ssh-credentials.json`（**私档**——用户域，仓库零落点；与 ⑨ 非密档 `ssh-hosts.json`
+ * 分档）。形 = `{ version: 1, entries: { "<host[:port]>": { user, scheme, blob, savedAt, lastUsedAt? } } }`
+ * ——值只以**密文 blob** 落盘（明文零落盘，NS6）。
+ *
+ * 加密 = Windows DPAPI（经系统 PowerShell 宿主）：加密 `ConvertTo-SecureString -AsPlainText -Force`
+ * → `ConvertFrom-SecureString`（无 `-Key` ⇒ DPAPI；Microsoft 文档逐字）；解密反之，Marshal 取明文。
+ * 通道纪律（§6.22 ⑦）：脚本 = 常量字面（**值不入命令行**）；值以 base64 封包经子进程 **stdin**，
+ * 密文 ∥ 解出明文经 **stdout**（hex ∥ base64——交换面全 ASCII）；子进程 env 删 `TC_SSH_SECRET`；
+ * 超时有界（到点杀子进程 ⇒ 按解密失败走 fail-soft）。
+ *
+ * fail-soft（§6.22 ⑪，逐形分判）：档缺失 ⇒ 视同无（静默）；结构损坏（JSON 不可解析）⇒ 视同无 +
+ * **原档原位不动**（下次成功保存整体覆盖重建）；不可解密 / 后端抛 ⇒ 条目保留（可能是暂时态）。
+ * 删除面只涉本档（⑨ 非密记录不随删）。
+ *
+ * 观测缝（A 面四格判据落形——S1/S6/N6/B7）：模块级读次计数 = **读盘入口调用数**；
+ * `_vaultReadsForTest()` / `_resetVaultReadsForTest()`——缺省生产行为不变，用例 `finally` 复位
+ * （同族先例 = §6.14 测试态缝）。
+ * 模块图：→ ssh-transport.mjs（`sshConfigDir` 测试缝单点）· ../i18n.mjs（窗词面单源）·
+ * node:child_process / node:fs——叶子向、无环。
+ */
+import { spawn } from "node:child_process"
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { t } from "../i18n.mjs"
+import { sshConfigDir } from "./ssh-transport.mjs"
+
+/** 保存件档名（与 ⑨ `ssh-hosts.json` 分档）。 */
+export const VAULT_FILE = "ssh-credentials.json"
+/** 档形版本（结构损坏判据之一）。 */
+export const VAULT_VERSION = 1
+/** 后端子进程超时（到点杀子进程 ⇒ 按解密失败走 fail-soft）。 */
+export const VAULT_TIMEOUT_MS = 15_000
+
+/** 加密脚本（常量字面——值经 stdin；`ConvertFrom-SecureString` 无 `-Key` ⇒ DPAPI）。 */
+const PS_ENCRYPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$b64 = [Console]::In.ReadToEnd().Trim()",
+  "$plain = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64))",
+  "$sec = ConvertTo-SecureString -String $plain -AsPlainText -Force",
+  "[Console]::Out.Write((ConvertFrom-SecureString -SecureString $sec))",
+].join("\n")
+/** 解密脚本（常量字面——hex 经 stdin；解出明文 base64 经 stdout）。 */
+const PS_DECRYPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$hex = [Console]::In.ReadToEnd().Trim()",
+  "$sec = ConvertTo-SecureString -String $hex",
+  "$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)",
+  "try { $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }",
+  "[Console]::Out.Write([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($plain)))",
+].join("\n")
+
+// ─── 观测缝（读次 = 读盘入口调用数）──────────────────────────────────────────
+
+let _reads = 0
+export function _vaultReadsForTest() { return _reads }
+export function _resetVaultReadsForTest() { _reads = 0 }
+
+// ─── 后端（DPAPI 经系统 PowerShell；测试缝只换命令，生产缺省不变）────────────
+
+let _backendCommand = null
+let _backendPrefix = []
+export function _setVaultBackendForTest(command, prefixArgs = []) {
+  _backendCommand = command
+  _backendPrefix = Array.isArray(prefixArgs) ? prefixArgs : []
+}
+export function _resetVaultBackendForTest() {
+  _backendCommand = null
+  _backendPrefix = []
+}
+
+const backendCommand = () => _backendCommand ?? "powershell.exe"
+/** 可用性单点（§6.22 裁决 ④：本批仅 Windows DPAPI；缺席 ⇒ 保存不可用，连接照常）。 */
+export const vaultAvailable = () => _backendCommand !== null || process.platform === "win32"
+
+/** 后端往返（脚本常量 + 输入 stdin → stdout；超时杀进程）。 */
+function runBackend(script, input) {
+  return new Promise((resolve, reject) => {
+    const env = { ...process.env }
+    delete env.TC_SSH_SECRET // 防残留（新增链路零 env；§6.22 ⑦）
+    const child = spawn(backendCommand(), [..._backendPrefix, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], {
+      stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env,
+    })
+    let out = ""
+    let err = ""
+    let done = false
+    const finish = (fn, value) => { if (done) return; done = true; clearTimeout(timer); fn(value) }
+    const timer = setTimeout(() => {
+      try { child.kill() } catch { /* 尽力面 */ }
+      finish(reject, new Error("vault backend timed out"))
+    }, VAULT_TIMEOUT_MS)
+    timer.unref?.()
+    child.stdout.on("data", (d) => { out += d })
+    child.stderr.on("data", (d) => { err += d })
+    child.on("error", (e) => finish(reject, new Error(`vault backend unavailable: ${e?.message ?? String(e)}`)))
+    child.on("exit", (code) => {
+      if (code !== 0) return finish(reject, new Error(`vault backend failed (${code}): ${err.trim().slice(0, 200)}`))
+      finish(resolve, out.trim())
+    })
+    child.stdin.on("error", () => { /* 退出竞态——判定面 = exit code */ })
+    child.stdin.end(input)
+  })
+}
+
+/** 加密：值 → hex 密文（值只经 stdin）。 */
+async function encryptValue(value) {
+  const b64 = Buffer.from(String(value), "utf8").toString("base64")
+  const hex = await runBackend(PS_ENCRYPT, b64)
+  if (!/^[0-9a-f]+$/i.test(hex)) throw new Error("vault backend returned an unexpected ciphertext")
+  return hex
+}
+
+/** 解密：hex 密文 → 明文（坏密文 / 后端抛 ⇒ reject——调用面走 fail-soft）。 */
+async function decryptBlob(blob) {
+  const b64 = await runBackend(PS_DECRYPT, String(blob ?? "").trim())
+  return Buffer.from(b64, "base64").toString("utf8")
+}
+
+// ─── 档（读 / 写 / 结构判定）────────────────────────────────────────────────
+
+const vaultFile = () => join(sshConfigDir(), VAULT_FILE)
+/** 读键单源（`host[:port]`，缺省 22；⑨ 记录面同引用）。 */
+export const hostKey = (host, port) => (port && Number(port) !== 22 ? `${host}:${port}` : String(host))
+
+/** 读盘入口（**唯一读次计数点**）。三态 = ok ∥ missing（静默视同无）∥ damaged（视同无，原档不动）。 */
+function readVaultFile() {
+  _reads += 1
+  let raw
+  try { raw = readFileSync(vaultFile(), "utf8") } catch (e) {
+    return e?.code === "ENOENT" ? { state: "missing" } : { state: "damaged", unreadable: true }
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    const entries = parsed?.entries
+    if (parsed?.version !== VAULT_VERSION || !entries || typeof entries !== "object" || Array.isArray(entries)) {
+      return { state: "damaged" }
+    }
+    return { state: "ok", entries }
+  } catch { return { state: "damaged" } }
+}
+
+/** 写盘单点（结构损坏的重建 = 调用面给空表整体覆盖——原档在此之前不动）。 */
+function writeVaultFile(entries) {
+  mkdirSync(sshConfigDir(), { recursive: true })
+  const body = JSON.stringify({ version: VAULT_VERSION, entries }, null, 2)
+  writeFileSync(vaultFile(), body, { encoding: "utf8", mode: 0o600 })
+  try { chmodSync(vaultFile(), 0o600) } catch { /* win32 无 POSIX mode——尽力面 */ }
+}
+
+/**
+ * 查条目（单次读盘）：条目 `user` 与「本次有效 `user`」不符 ⇒ 视同无（⑪）。
+ * @returns {{ state: "ok", key: string, entry: object } | { state: "missing"|"damaged"|"unreadable" }}
+ */
+export function getEntry(host, port, user) {
+  const read = readVaultFile()
+  if (read.state !== "ok") return { state: read.state }
+  const key = hostKey(host, port)
+  const entry = read.entries[key]
+  if (!entry || typeof entry !== "object") return { state: "missing" }
+  if (!user || entry.user !== user) return { state: "missing" }
+  return { state: "ok", key, entry }
+}
+
+/**
+ * 复用终段：读条目 → 解密。失败形分判（调用面各自回落窗 / 可读句）：
+ * `missing`（静默）· `damaged`（可读句）· `unavailable`（后端缺席）· `undecryptable`（条目保留）。
+ * @returns {Promise<{ state: "ok", key: string, value: string } | { state: string }>}
+ */
+export async function resolveSecret(host, port, user) {
+  const got = getEntry(host, port, user)
+  if (got.state !== "ok") return { state: got.state }
+  if (!vaultAvailable()) return { state: "unavailable" }
+  try {
+    const value = await decryptBlob(got.entry.blob)
+    if (!value.length) return { state: "undecryptable" } // 解出空值 = 不可用（不当空口令提交）
+    return { state: "ok", key: got.key, value }
+  } catch { return { state: "undecryptable" } }
+}
+
+/**
+ * 保存（窗内勾选且认证成功后调用）：加密 → 整体写档（结构损坏的旧档在此被覆盖重建）。
+ * @returns {Promise<{ ok: true, key: string } | { ok: false, reason: string }>}
+ */
+export async function saveEntry(host, port, { user, value } = {}) {
+  if (!vaultAvailable()) return { ok: false, reason: "unavailable" }
+  if (!String(value ?? "").length) return { ok: false, reason: "empty" }
+  let blob
+  try { blob = await encryptValue(value) } catch { return { ok: false, reason: "backend" } }
+  try {
+    const read = readVaultFile()
+    const entries = read.state === "ok" ? { ...read.entries } : {}
+    const key = hostKey(host, port)
+    entries[key] = { user: user ?? null, scheme: "dpapi", blob, savedAt: new Date().toISOString() }
+    writeVaultFile(entries)
+    return { ok: true, key }
+  } catch { return { ok: false, reason: "write" } }
+}
+
+/** 删除（`forget`）：条目不存在 ⇒ 幂等（existed:false）；结构损坏 ⇒ 原档不动（可读句）。 */
+export function deleteEntry(host, port) {
+  const key = hostKey(host, port)
+  const read = readVaultFile()
+  if (read.state === "missing") return { ok: true, existed: false }
+  if (read.state !== "ok") return { ok: false, reason: "damaged" }
+  if (!Object.hasOwn(read.entries, key)) return { ok: true, existed: false }
+  const entries = { ...read.entries }
+  delete entries[key]
+  try { writeVaultFile(entries) } catch { return { ok: false, reason: "write" } }
+  return { ok: true, existed: true }
+}
+
+/** `lastUsedAt` = 复用成功时更新；写失败 = 增益面静默（⑪）。 */
+export function touchEntry(host, port) {
+  const read = readVaultFile()
+  if (read.state !== "ok") return
+  const key = hostKey(host, port)
+  const entry = read.entries[key]
+  if (!entry || typeof entry !== "object") return
+  try { writeVaultFile({ ...read.entries, [key]: { ...entry, lastUsedAt: new Date().toISOString() } }) } catch { /* 增益面静默 */ }
+}
+
+// ─── 凭据获取链（§6.22 ⑧：`ctx.onSecretInput` 窗）────────────────────────────
+
+/** 凭据窗（§6.22 ⑧）：无 UI ⇒ 可读错（不挂起、不静默——`question.mjs` 无 UI 抛例同旨）；词面 = i18n 键。
+ *  端侧回调自身拒绝（CLI `refuseSecretInput()` 形：抛可读句）⇒ 同族直出（`noUi` 标记 = 失败句不另加前缀）。
+ *  `offerSave` ⇒ `fields` += `save`（`checkbox: true`——缺省不勾（opt-in）；提交值 = 布尔；核侧严格判 `=== true`）。
+ *  拆档由 = 会话面超 500 顾问线（拆前 ≈513 行；设计 490 再拆线 ⇒ 按落点表候选拆分「凭据获取链迁入 `ssh-vault.mjs`」）。 */
+export async function askCredential(ctx, { host, user, port, sessionId, offerSave = false }) {
+  if (typeof ctx?.onSecretInput !== "function") {
+    const err = new Error(t("ssh.no_ui"))
+    err.noUi = true // 可读句直出（catch 面不另加前缀——失败句单源 = 核字典）
+    throw err
+  }
+  const fields = [
+    { name: "user", masked: false, required: false, prefill: user ?? "" },
+    { name: "password", masked: true, required: true, prefill: "" },
+  ]
+  if (offerSave) fields.push({ name: "save", masked: false, required: false, prefill: false, checkbox: true })
+  let res
+  try {
+    res = await ctx.onSecretInput({
+      kind: "ssh-credential",
+      sessionId: sessionId != null ? `ssh#${sessionId}` : null,
+      host, user: user ?? null, port: port ?? null,
+      fields,
+      keys: { title: "ssh.credentialTitle", prompt: "ssh.credentialPrompt" },
+    })
+  } catch (e) {
+    // 端侧拒绝（无交互面 / 载荷成形外）⇒ 同族可读句直出（不裹「connect failed」前缀）。
+    const err = new Error(e?.message ?? String(e))
+    err.noUi = true
+    throw err
+  }
+  if (!res || typeof res !== "object") return null
+  return res
+}
+
+// ─── 保存凭据管理面（§6.22 ⑫：`credentials` 只读 ∥ `forget` 写——核单点，三端同源）────────────
+
+/** `credentials`（只读免审）：host / user / 保存时间 / 最近使用——**值零出现**（清单不含 blob）。 */
+export function credentialsSsh() {
+  const read = readVaultFile()
+  if (read.state === "missing") return { text: "(no saved ssh credentials)" }
+  if (read.state !== "ok") return { text: "saved ssh credentials: the store is damaged — the file was left untouched; delete it manually to reset the store" }
+  const rows = Object.entries(read.entries)
+    .map(([key, e]) => ({ key, user: e?.user ?? null, savedAt: e?.savedAt ?? null, lastUsedAt: e?.lastUsedAt ?? null }))
+    .sort((a, b) => a.key.localeCompare(b.key))
+  if (rows.length === 0) return { text: "(no saved ssh credentials)" }
+  const head = vaultAvailable()
+    ? "saved ssh credentials (encrypted with this Windows user account):"
+    : "saved ssh credentials (the credential store is not available on this platform):"
+  const lines = rows.map((r) => {
+    const saved = r.savedAt ? ` \u00b7 saved ${r.savedAt}` : ""
+    const used = r.lastUsedAt ? ` \u00b7 last used ${r.lastUsedAt}` : ""
+    return `[${r.key}]${r.user ? ` user ${r.user}` : ""}${saved}${used}`
+  })
+  return { text: `${head}\n${lines.join("\n")}` }
+}
+
+/** `forget`（写动作——过既有审批门）：按 `host` + 可选 `port` 删条目；幂等；值零出现。
+ *  删除 ⇒ 下次连接回落凭据窗（S8）；只涉保存档（⑨ 非密记录不随删）。 */
+export function forgetSsh({ host, port } = {}) {
+  const key = hostKey(host, port)
+  const res = deleteEntry(host, port)
+  if (!res.ok) return { error: `could not update the saved-credential store (${res.reason}) — the file was left untouched` }
+  if (!res.existed) return { text: `no saved credential for ${key} — nothing to forget (the call is idempotent)` }
+  return { text: `saved credential for ${key} deleted — the next connect asks in the credential window` }
+}

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)