@thincoder/core 0.10.8 → 0.10.10

package/agent-tools/ssh-session.mjs

@@ -7,14 +7,17 @@
  * - 池：`_sshSessions`（照 `bash-async.mjs` 池先例——载体经 `carrierField` 吸收）；帽 `SSH_SESSION_MAX = 4`
  *   条存活会话；超限**显式拒**（零静默关旧）。
  * - 连接（预探路——父侧 2026-10-14 裁定 A）：探连 = **全会话形** + `NumberOfPasswordPrompts=0`；探连成功
- *   ⇒ **该连接直接升格为会话**（密钥机全程恰 1 次连接）；认证类失败 ⇒ 终止探连 → 弹凭据窗 → **单次**
- *   带密会话（`NumberOfPasswordPrompts=1`）；指纹 / 不可达 / 连接超时 ⇒ **弹窗之前硬停**（E3 语义）。
+ *   ⇒ **该连接直接升格为会话**（密钥机全程恰 1 次连接）；认证类失败 ⇒ 终止探连 → **先读保存件**（⑪
+ *   命中 ⇒ 直接带密会话，零窗）→ 无 / 不可用 ⇒ 弹凭据窗 → **单次**带密会话（`NumberOfPasswordPrompts=1`）；
+ *   指纹 / 不可达 / 连接超时 ⇒ **弹窗之前硬停**（E3 语义）。
+ * - 保存面（用户裁定 A+B · 台账 #1602）：⑩ 身份面（`identityFile` / `auth` 随 ⑨ 记录）∥ ⑪ 保存件读写 /
+ *   解密 / `lastUsedAt` / fail-soft / 窗内勾选 ⇒ 单点 `agent-tools/ssh-vault.mjs`；⑫ `credentials` / `forget`。
  * - 生命周期：闲置 600 s 自动关（digest 注记）· `close` = stdin 结束 → 1.5 s 宽限 → 杀树 · 回合中断存活
  *   （F2 豁免）· 会话中止逐条杀 + 清池（`agent-tools/async-discard.mjs` `SSH_SPEC`）· depth>0 排除
  *   （`agent/helpers.mjs` `SUBAGENT_TOOL_EXCLUSIONS`）。
- * 模块图：→ ssh-transport.mjs（运行面）· agent/helpers.mjs（轮转清理）· tools/process-tree.mjs（树杀）·
- * context.mjs（pushReal）· async-settle.mjs（池 ∥ 载体 ∥ 墓碑 ∥ 控制器链）· subagent-scheduler.mjs
- * （取号 ∥ 令牌 ∥ 入池守卫）——叶子向、无环。
+ * 模块图：→ ssh-transport.mjs（运行面）· ssh-vault.mjs（保存件单点）· agent/helpers.mjs（轮转清理）·
+ * tools/process-tree.mjs（树杀）· context.mjs（pushReal）· async-settle.mjs（池 ∥ 载体 ∥ 墓碑 ∥ 控制器链）·
+ * subagent-scheduler.mjs（取号 ∥ 令牌 ∥ 入池守卫）——叶子向、无环。
  */
 import { createWriteStream, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
@@ -27,10 +30,11 @@ import {
 } from "./async-settle.mjs"
 import { assertPoolKeyFree, consumeSubagentToken, nextSubagentId } from "./subagent-scheduler.mjs"
 import {
-  SSH_RETURN_CAP, SSH_SETTLE_MS, SSH_TIMEOUT_MS, bodyText, capText, classifyFailure, createMask, drain,
+  SSH_KEEPALIVE_MS, SSH_RETURN_CAP, SSH_SETTLE_MS, SSH_TIMEOUT_MS, bodyText, capText, classifyFailure, createMask, drain,
   failureText, idLabel, settleNote, sshConfigDir, spawnSession, statusLine, unlinkAskpass, waitSettled,
   writeAskpassWrapper,
 } from "./ssh-transport.mjs"
+import { askCredential, deleteEntry, hostKey, resolveSecret, saveEntry, touchEntry, vaultAvailable } from "./ssh-vault.mjs"
 
 /** 并存活会话帽（照 `BG_TASK_MAX` 族）。超限显式拒。 */
 export const SSH_SESSION_MAX = 4
@@ -42,10 +46,16 @@ const CLOSE_GRACE_MS = 1500
 /** 非密预填档（§6.22 ⑨）：`configDir/ssh-hosts.json`——白名单字段，密码零字段。 */
 const HOSTS_FILE = "ssh-hosts.json"
 
-/** 测试缝（闲置窗缩短——生产从不调用）。 */
-let _idleMs = null
-export function _setSshIdleMsForTest(ms) { _idleMs = ms }
-const idleMs = () => _idleMs ?? SSH_IDLE_MS
+/** 测试态时间缝（B3 ∥ S2 ∥ S4 判据落形——§6.22 ④）：闲置 `idleMs` ∥ 保活 `keepAliveMs`；
+ *  缺省取常量、传值 `??` 回落、`finally` 复位（`_resetSshTimeoutsForTest`）；**不进用户参数面**。 */
+let _timeouts = { idleMs: null, keepAliveMs: null }
+export function _setSshTimeoutsForTest({ idleMs, keepAliveMs } = {}) {
+  if (idleMs !== undefined) _timeouts.idleMs = idleMs ?? null
+  if (keepAliveMs !== undefined) _timeouts.keepAliveMs = keepAliveMs ?? null
+}
+export function _resetSshTimeoutsForTest() { _timeouts = { idleMs: null, keepAliveMs: null } }
+const idleMs = () => _timeouts.idleMs ?? SSH_IDLE_MS
+const keepAliveMs = () => _timeouts.keepAliveMs ?? SSH_KEEPALIVE_MS
 const toolResultsDir = () => join(sshConfigDir(), "tool-results")
 
 /** 池（写侧：父字段优先 / 借用 history 载体——`ensureBgPool` 同式）。 */
@@ -155,8 +165,6 @@ export function killSshTree(entry) {
 // ─── 非密预填档（§6.22 ⑨）──────────────────────────────────────────────────
 
 const hostsFile = () => join(sshConfigDir(), HOSTS_FILE)
-/** 读键 = `host[:port]`（缺省 22）。 */
-const hostKey = (host, port) => (port && Number(port) !== 22 ? `${host}:${port}` : String(host))
 
 function lookupHostRecord(host, port) {
   try {
@@ -166,15 +174,20 @@ function lookupHostRecord(host, port) {
   } catch { return null }
 }
 
-/** 写入 = **认证成功后**；白名单 = 非密字段（host / port / user / lastUsedAt——密码零字段）。 */
-function saveHostRecord(host, port, user) {
-  if (!user) return
+/** 写入 = **认证成功后**；白名单 = 非密字段（host / port / user / lastUsedAt / `identityFile` / `auth`——
+ *  密码零字段；⑩ 身份面）。无 `user` 但有 `identityFile` 时也写（身份面复用不依赖 user 预填）。 */
+function saveHostRecord(host, port, user, { identity = null, auth = null } = {}) {
+  if (!user && !identity) return
   try {
     mkdirSync(sshConfigDir(), { recursive: true })
     let all = {}
     try { all = JSON.parse(readFileSync(hostsFile(), "utf8")) ?? {} } catch { all = {} }
     if (typeof all !== "object" || all === null) all = {}
-    all[hostKey(host, port)] = { host, port: Number(port) || 22, user, lastUsedAt: new Date().toISOString() }
+    all[hostKey(host, port)] = {
+      host, port: Number(port) || 22, user: user ?? null, lastUsedAt: new Date().toISOString(),
+      ...(identity ? { identityFile: identity } : {}),
+      ...(auth ? { auth } : {}),
+    }
     writeFileSync(hostsFile(), JSON.stringify(all, null, 2), "utf8")
   } catch { /* 预填 = 增益面——写失败不进连接语义 */ }
 }
@@ -182,10 +195,12 @@ function saveHostRecord(host, port, user) {
 // ─── 动作（工具面薄接线消费）────────────────────────────────────────────────
 
 /**
- * 连接（§6.22 ⑤ + 裁定 A 预探路）：探连 ⇒ 升格 ∥ 认证失败 ⇒ 凭据窗 ⇒ 单次带密会话。
+ * 连接（§6.22 ⑤ + 裁定 A 预探路 + 保存面）：探连 ⇒ 升格 ∥ 认证失败 ⇒ **先读保存件**（命中 ⇒ 带密
+ * 会话零窗）⇒ 无 / 不可用 / 被拒 ⇒ 凭据窗（窗内可勾选保存）⇒ 单次带密会话。
+ * 优先级铁序（⑩）：保存件**恒不先于探连**——密钥可用 ⇒ 保存件零读取（S6/N6/B7）。
  * @returns {{ text?: string, error?: string }}
  */
-export async function connectSsh(parent, ctx, { host, user, port, label, promptPattern } = {}) {
+export async function connectSsh(parent, ctx, { host, user, port, label, promptPattern, identityFile } = {}) {
   if (!parent) return { error: "no agent context — ssh sessions need a session-level pool (depth-0 only)" }
   if (typeof host !== "string" || !host.trim()) return { error: "connect requires host" }
   const pool = sshPool(parent)
@@ -201,8 +216,9 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
     try { promptRe = new RegExp(String(promptPattern)) } catch (e) { return { error: `promptPattern is not a valid regex: ${e.message}` } }
   }
   const record = lookupHostRecord(host, port)
-  const effectiveUser = user || record?.user || null
+  const effectiveUser = user || record?.user || null // 判定序：connect 参数 → ⑨ 记录 → 皆缺视同无
   const userFromRecord = !user && record?.user ? record.user : null
+  const identity = identityFile || record?.identityFile || null // ⑩：参数 → ⑨ 记录
   const id = nextSubagentId(parent)
   consumeSubagentToken(parent, id, "ssh connect", "ssh")
   await cleanupOldToolResults(toolResultsDir())
@@ -222,25 +238,37 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
     const reason = await waitSettled(entry, { signal: ctx?.signal ?? null })
     return { reason, waitedMs: Date.now() - t0 }
   }
-  /** 升格为会话（探连成功 ∥ 带密会话成功同径）。 */
-  const promote = (reason, waitedMs) => {
+  /** 起跑（探连 ∥ 带密会话同径；`-i` 两径同带——追加候选身份，不夺既有尝试序列）。
+   *  每次起跑前清该轮缓冲：分类 / 沉降只看**本次连接**的输出（探连错误的残渣不得误判下一次尝试）。 */
+  const spawn = (sessionUser, secret) => {
+    entry.buf = ""
+    entry.bufDropped = false
+    return spawnSession(entry, { user: sessionUser, port, secret, identityFile: identity, keepAliveMs: keepAliveMs() })
+  }
+  /** 升格为会话（探连成功 ∥ 带密会话成功同径）；⑩ 身份面（auth）随 ⑨ 记录回写。 */
+  const promote = (reason, waitedMs, { auth = "key", extra = [] } = {}) => {
     entry.state = "ready"
     entry.lastActivityAt = Date.now()
     armIdle(entry)
-    saveHostRecord(entry.host, entry.port, entry.user)
+    saveHostRecord(entry.host, entry.port, entry.user, { identity, auth })
     const { text, dropped } = drain(entry)
     const notes = [
       `— connected (${settleNote(entry, reason, waitedMs)})`,
       `log: ${entry.logPath}`,
       userFromRecord ? `user "${userFromRecord}" came from the local ssh-hosts record` : "",
+      ...extra,
       dropped ? "in-memory buffer overflowed — full output in the log" : "",
     ].filter(Boolean)
     return { text: `${statusLine(entry)}\n${bodyText(capText(text, SSH_RETURN_CAP, entry))}\n${notes.join("; ")}` }
   }
+  /** 认证类失败分类（spawn 错误 ∥ 输出判据——两径同式）。 */
+  const classify = () => (entry.spawnError
+    ? { kind: "spawn", message: `ssh client not available (${entry.spawnError}) — install system OpenSSH or check PATH` }
+    : classifyFailure(entry.buf))
   try {
     assertPoolKeyFree(pool, id, "ssh")
     pool.set(String(id), entry)
-    spawnSession(entry, { user: effectiveUser, port, secret: null }) // 探连：全会话形 + NumberOfPasswordPrompts=0
+    spawn(effectiveUser, null) // 探连：全会话形 + NumberOfPasswordPrompts=0（不读保存件——铁序）
     let { reason, waitedMs } = await settle()
     // 「已就绪」判据要求进程尚在（静默窗与退出同刻的竞争面——升格一条死连接不成立）。
     if ((reason === "prompt" || reason === "silence") && entry.exitInfo) reason = "exited"
@@ -252,20 +280,54 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
       hardClose(entry, "closed", "consumed")
       return { error: `ssh connect did not settle within ${SSH_TIMEOUT_MS}ms (${entry.host}) — the connection is closed; retry or increase the wait` }
     }
+    let auth = "key"
+    const flowNotes = []
     if (reason === "exited") {
-      const cls = entry.spawnError
-        ? { kind: "spawn", message: `ssh client not available (${entry.spawnError}) — install system OpenSSH or check PATH` }
-        : classifyFailure(entry.buf)
+      const cls = classify()
       if (!cls || cls.kind !== "auth") {
         const text = failureText(entry, cls)
         hardClose(entry, "closed", "connect-failed") // 杀树收尾（finalize 只出池——活子进程会成无句柄悬挂）
         return { error: text }
       }
-      // 认证类失败 ⇒ 凭据窗（值只走回调返回路 + 子进程环境——NS4：零入参 ∥ 零入结果 ∥ 零落盘）。
-      const input = await askCredential(ctx, { host, user: effectiveUser, port, sessionId: id })
+      // 认证类失败 ⇒ **先读保存件**（⑪；有效 user 判定序缺 ⇒ 零消费零删除——直接落窗）。
+      let saved = null
+      let failNote = ""
+      if (effectiveUser) {
+        const got = await resolveSecret(host, port, effectiveUser)
+        if (got.state === "ok") saved = got
+        else if (got.state === "damaged") failNote = "the saved-credential store is damaged — it was left untouched"
+        else if (got.state === "undecryptable") failNote = "the saved credential could not be decrypted — the entry was kept"
+        else if (got.state === "unavailable") failNote = "saved credentials are not available on this platform"
+        // missing ⇒ 静默（正常首连态）
+      }
+      if (saved) {
+        entry.user = effectiveUser
+        entry.mask.add(saved.value) // 遮蔽先注册后写入（回显面零泄）
+        spawn(entry.user, saved.value) // 带密会话（PP=1）——命中保存件 ⇒ 零窗
+        ;({ reason, waitedMs } = await settle())
+        if ((reason === "prompt" || reason === "silence") && entry.exitInfo) reason = "exited"
+        if (reason === "prompt" || reason === "silence") {
+          touchEntry(host, port) // lastUsedAt = 复用成功时更新（写失败 = 增益面静默）
+          return promote(reason, waitedMs, { auth: "password", extra: ["saved credential used (no credential window)"] })
+        }
+        const clsSaved = classify()
+        // 只有**本次进程正常退出且为认证类**才算「服务端拒绝」；超时 / 中断 / 不可达 ⇒ 条目保留、硬停。
+        if (reason !== "exited" || clsSaved?.kind !== "auth") {
+          const text = failureText(entry, clsSaved ?? { message: "authentication rejected" }, " — the session was not established")
+          hardClose(entry, "closed", "connect-failed")
+          return { error: text }
+        }
+        // 条目被服务端拒 ⇒ 删该条目（拒绝即值已失效——避免每次重试旧值）+ 回落窗；删失败时注记如实。
+        const del = deleteEntry(host, port)
+        failNote = del.ok
+          ? "the saved credential was rejected by the server — the entry was deleted"
+          : "the saved credential was rejected by the server — the store could not be updated (the entry may still be there)"
+      }
+      // 凭据窗（值只走回调返回路 + 子进程环境——NS4：零入参 ∥ 零入结果 ∥ 零落盘）。
+      const input = await askCredential(ctx, { host, user: effectiveUser, port, sessionId: id, offerSave: vaultAvailable() })
       if (!input) {
         hardClose(entry, "closed", "consumed")
-        return { error: `ssh connect to ${entry.host} cancelled — no credential was provided (no connection was attempted with one)` }
+        return { error: `ssh connect to ${entry.host} cancelled — no credential was provided (no connection was attempted with one)${failNote ? ` (${failNote}; the credential window was shown)` : ""}` }
       }
       if (!String(input.password ?? "").length) {
         hardClose(entry, "closed", "consumed")
@@ -273,7 +335,7 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
       }
       entry.user = input.user || effectiveUser || null
       entry.mask.add(input.password) // 遮蔽先注册后写入（回显面零泄）
-      spawnSession(entry, { user: entry.user, port, secret: input.password }) // 单次带密会话（PP=1）
+      spawn(entry.user, input.password) // 单次带密会话（PP=1）
       ;({ reason, waitedMs } = await settle())
       if ((reason === "prompt" || reason === "silence") && entry.exitInfo) reason = "exited"
       if (reason !== "prompt" && reason !== "silence") {
@@ -283,8 +345,19 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
         hardClose(entry, "closed", "connect-failed")
         return { error: text }
       }
+      // 认证成功后才写（opt-in——严格布尔；写失败不影响连接：增益面语义）
+      if (input.save === true && entry.user) {
+        const savedRes = await saveEntry(host, port, { user: entry.user, value: input.password })
+        flowNotes.push(savedRes.ok
+          ? "the credential was saved for this host (encrypted with this Windows user account)"
+          : "the credential could not be saved (the connection is unaffected)")
+      } else if (input.save === true) {
+        flowNotes.push("the credential was not saved (no login user was given for this host)")
+      }
+      if (failNote) flowNotes.unshift(`${failNote}; the credential window was shown`)
+      auth = "password"
     }
-    return promote(reason, waitedMs)
+    return promote(reason, waitedMs, { auth, extra: flowNotes })
   } catch (e) {
     hardClose(entry, "closed", "connect-failed") // 异常径同走杀树（子进程可能仍在飞）
     return { error: e?.noUi ? `Error: ${e.message}` : `ssh connect failed: ${e?.message ?? String(e)}` }
@@ -293,36 +366,6 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
   }
 }
 
-/** 凭据窗（§6.22 ⑧）：无 UI ⇒ 可读错（不挂起、不静默——`question.mjs` 无 UI 抛例同旨）；词面 = i18n 键。
- *  端侧回调自身拒绝（CLI `refuseSecretInput()` 形：抛可读句）⇒ 同族直出（`noUi` 标记 = 失败句不另加前缀）。 */
-async function askCredential(ctx, { host, user, port, sessionId }) {
-  if (typeof ctx?.onSecretInput !== "function") {
-    const err = new Error(t("ssh.no_ui"))
-    err.noUi = true // 可读句直出（catch 面不另加前缀——失败句单源 = 核字典）
-    throw err
-  }
-  let res
-  try {
-    res = await ctx.onSecretInput({
-      kind: "ssh-credential",
-      sessionId: sessionId != null ? `ssh#${sessionId}` : null,
-      host, user: user ?? null, port: port ?? null,
-      fields: [
-        { name: "user", masked: false, required: false, prefill: user ?? "" },
-        { name: "password", masked: true, required: true, prefill: "" },
-      ],
-      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
-}
-
 /** 缓冲溢出注记（三动作同式——丢弃面显式化；全量恒在 log）。 */
 const droppedNote = (dropped) => (dropped ? "\n— in-memory buffer overflowed — full output in the log" : "")
 
@@ -437,3 +480,7 @@ export function listSsh(parent) {
 // 常量转口（工具面 / 测试档经本档取——机制档不重复导出）。
 export { SSH_SETTLE_MS, SSH_TIMEOUT_MS, SSH_RETURN_CAP }
 export { _setSshBinaryForTest, _setSshConfigDirForTest } from "./ssh-transport.mjs"
+
+// 保存凭据管理面（§6.22 ⑫）：`credentials` / `forget` 实体 = `ssh-vault.mjs`（核单点——本档只转口；
+// 拆档由 = 机制档触 500 顾问线，§6.22 落点表候选拆分）。
+export { credentialsSsh, forgetSsh } from "./ssh-vault.mjs"

package/agent-tools/ssh-transport.mjs

@@ -17,6 +17,7 @@
  */
 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"
@@ -28,6 +29,8 @@ export const SSH_SETTLE_MS = 800
 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）。 */
@@ -81,18 +84,28 @@ 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 两径同被短路——
  *  `sshconnect2.c` `userauth_passwd` / `userauth_kbdint` 两处同判 `attempt++ >= n`；私钥口令提示
  *  亦被短路：`load_identity_file` 循环 `i <= number_of_password_prompts`）；带密 = 1（单提示）。 */
-export function buildSshArgs({ host, user, port, probe }) {
+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=30",
+    "-o", `ServerAliveInterval=${keepAliveS}`,
     "-o", "ServerAliveCountMax=4",
     "-o", `NumberOfPasswordPrompts=${probe ? 0 : 1}`,
     ...(port ? ["-p", String(port)] : []),
+    ...(identityFile ? ["-i", expandHome(identityFile)] : []),
     user ? `${user}@${host}` : host,
   ]
 }
@@ -184,10 +197,10 @@ export function attachChild(entry, child) {
 
 /** 起跑一条 ssh（探连 ∥ 带密会话同径）。重起（探连 → 带密会话）⇒ 判定面复位：exitInfo ∥
  *  spawnError 属**上一次**进程（残留会让新连接的成功判定被误读成「已退出」）。 */
-export function spawnSession(entry, { user, port, secret }) {
+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 })], {
+  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",

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` }
+}