@thincoder/core 0.10.8 → 0.10.9

package/agent-tools/doc-check.mjs

@@ -1,19 +1,28 @@
 /**
- * agent-tools/doc-check.mjs — `doc_check` 工具：文档纪律机检（产品内建 · 报告态 · 非门禁）。
+ * agent-tools/doc-check.mjs — `doc_check` 工具：文档纪律机检（产品内建 · 两种问法）。
  *
- * 设计 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S（起步两条判据 = 锚 ∥ 行宽 · 声明面驱动）。
- * 工具形：**单动作**（无 action 枚举——不预建空枚举）· **只读**（零副作用 · 免审批 · 可并行）·
- * 参数 `target` 可选（缺省 = 会话锚）；`target` 指向多项目工作区 ⇒ 报明候选并要求指名（同 `manifest` 工具面）。
+ * 设计 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S（判据 = 锚 ∥ 行宽 · 声明面驱动）。
+ * 工具形：**无动作枚举**——`mode` = 同一条判据的两种问法（`report` = 全域报告态 ∥ `gate` = 交付时点
+ * 的范围化裁定）；**只读**（零副作用 · 免审批 · 可并行）；参数 `target` / `mode` / `docs`
+ * （`target` 指向多项目工作区 ⇒ 报明候选并要求指名，同 `manifest` 工具面）。
  * 判据参数读目标项目的 `PROJECT-MANIFEST.json` `checkConfig`——不硬编码任何本仓路径（换项目开箱可用）。
- * 非门禁（硬）：输出不得被读作拒执行的理由（用户令 > 机检——§2 总则族）。
+ * `report` 非门禁（硬）：输出不得被读作拒执行的理由（用户令 > 机检——§2 总则族）；
+ * `gate` 的强制面住交付协议 + 批次档 §6 前置，工具本体同样不阻断任何动作。
+ * gate 前置（fail-closed）= 引擎版本一致：本会话进程持启动时加载的 ESM 引擎，引擎档晚于启动 ⇒ ERROR
+ * （判据单源 = `doc-check/version.mjs`——与 `batch-gate.mjs` 共用一份清单，不各持一份）。
  * 描述外置：模型可见文本单点 = `tool-docs/doc_check.md`（`DESC` 单一解析面）。
  * 装配段 = `agent/family-tools.mjs` 三处（depth-0 / eng-coder / eng-designer）——写文档 / 设计档的角色面。
  */
 import { resolve } from "node:path"
 import { projectRootView } from "../manifest.mjs"
 import { runDocCheck } from "../doc-check/index.mjs"
+import { staleEngineFiles, gateEngineError, withEngineNote } from "../doc-check/version.mjs"
 import { DESC } from "../tools/shared.mjs"
 
+// 版本函数单源 = `doc-check/version.mjs`（两消费面：本档 gate 分支 ∥ `batch-gate.mjs` 两机械点）——
+// 本档只转口，导出面不变（原五档清单已随之六档：`version.mjs` 自身入清单）。
+export { staleEngineFiles, gateEngineError }
+
 export const docCheckTool = {
   name: "doc_check",
   description: DESC("doc_check"),
@@ -21,17 +30,46 @@ export const docCheckTool = {
     type: "object",
     properties: {
       target: { type: "string", description: "Explicit project root to check — defaults to the session anchor; relative paths resolve against it. A workspace target (several projects below it) is reported with the full candidate list — pass the project root you mean." },
+      mode: { type: "string", enum: ["report", "gate"], description: "How to ask the same two-criteria check. \"report\" (default): the whole declared domain, non-gating report. \"gate\": the delivery gate — only the documents this round touched, whole-file judged, first line a machine-readable verdict (DOC-CHECK GATE: PASS / REFUSED / ERROR)." },
+      docs: { type: "array", items: { type: "string" }, description: "Gate only: the documents this round touched (paths relative to the project root, or absolute). Omitted in gate mode ⇒ the documents this session wrote. Passing docs with mode \"report\" is refused, not silently ignored." },
     },
   },
   readonly: true,
   execute(args, ctx) {
     const anchor = ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
     const target = args?.target ? resolve(anchor, String(args.target)) : resolve(anchor)
+    const mode = args?.mode === undefined ? "report" : String(args.mode)
+    if (mode !== "report" && mode !== "gate") return `doc_check: unknown mode "${mode}" — use "report" (default: the whole declared domain) or "gate" (this round's documents).`
+    const explicit = Array.isArray(args?.docs) ? args.docs.map(String) : null
+    if (args?.docs !== undefined && !Array.isArray(args.docs)) {
+      return `doc_check: \`docs\` must be an array of paths (got ${typeof args.docs}) — a bare string is refused rather than read as a whole-domain request; pass ["<path>"].`
+    }
+    if (mode === "report" && explicit) {
+      return "doc_check: `docs` is only valid with mode:\"gate\" — report mode always checks the whole declared domain; pass mode:\"gate\" to scope the check to the documents this round touched."
+    }
     const view = projectRootView(target)
     if (view.state === "workspace") {
+      if (mode === "gate") {
+        return [
+          "DOC-CHECK GATE: ERROR（多项目工作区：请指名 target）",
+          `候选：${view.candidates.join(" ∥ ")}`,
+          "处置：指名项目根（`target`）后复跑",
+        ].join("\n")
+      }
       return `doc_check: ${target} is a workspace holding ${view.candidates.length} projects — pass the project root explicitly via target:\n` +
         view.candidates.map((c) => `- ${c}`).join("\n")
     }
-    return runDocCheck(view.state === "ok" ? view.root : target).report
+    const root = view.state === "ok" ? view.root : target
+    if (mode === "gate") {
+      // 引擎版本校验先于引擎（A-DD30 ①）：stale 非空 ⇒ 直接 ERROR 串，不进引擎
+      const version = staleEngineFiles()
+      if (version.stale.length) return gateEngineError(version)
+      // 会话候选先取 `.md`（触达记账含代码档——代码档不是文档，不该进范围行）；域求交归引擎单源
+      const docs = explicit ?? (Array.isArray(ctx?.agent?._touchedFiles) ? ctx.agent._touchedFiles : [])
+        .filter((p) => typeof p === "string" && p.toLowerCase().endsWith(".md"))
+      return runDocCheck(root, { mode: "gate", docs, docsSource: explicit ? "explicit" : "session" }).report
+    }
+    // 报告态读数标注（A-DD30 ①）：引擎陈旧 ⇒ 首行前一行注记；无陈旧 ⇒ 报面逐字同改前
+    return withEngineNote(runDocCheck(root).report, staleEngineFiles())
   },
 }

package/agent-tools/spawn-gates.mjs

@@ -1,52 +1,40 @@
 /**
  * spawn-gates.mjs — M5 委派与 spawn 门新门禁统一落点（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：
  * 全部新增门禁逻辑集中于此——装配点（buildSpawnChild / normalizeFileList）只加 import 调用。
- * 已实现：F2（round 结构化参数 + 任务书五段文本字段校验）· F6（files 声明面拦截谓词）。
+ * 已实现：F2（round 枚举 + 任务书参数校验/拼装——四项核心 + 第五项按角色）· F6（files 声明面拦截谓词）。
  * 裁撤（2026-09-17 主 agent 裁定——不落代码）：
- *   - F4 修复轮窄带：全量勘察散文 marker 不可机判（误拒风险不可接受）→ 由 F2 五段字段覆盖；
+ *   - F4 修复轮窄带：全量勘察散文 marker 不可机判（误拒风险不可接受）→ 由 F2 的 round 参数承载轮次语义；
  *   - F5 advisor 角色：advisor 不入 spawn 通道（评审走 advisor 工具）——enum 收正为
  *     explore/eng-designer/eng-coder。
  * 零依赖：本模块零 import（叶子——纯谓词层，无环、无反向依赖）。
  */
 
-/**
- * F2 任务书五段文本字段（六强制字段中 round 之外的五段——ENGINEERING-MODE-V2-MODULE-DELEGATION §1.2 F2）。
- * 判据 = 段标题在场（标题行或行内 marker——summaryEngTaskBook 同款手法：marker 正则命中
- * task ∪ context 文本即可）；内容够不够由执行者拒收兜底（需求 §1.14 #9 行为面——不做内容校验）。
- * 双语 marker：中文标题（主 agent 派单形）与英文标题（交付报告格式模板形）同收。
- */
-const TASK_BOOK_FIELDS = [
-  { label: "目标与理由 (goal & why)", markers: [/目标与理由/, /goal\s*&\s*why/i, /goal\s+and\s+why/i] },
-  { label: "已知事实 (known facts)", markers: [/已知事实/, /known\s+facts/i] },
-  { label: "设计要点与禁止范围 (design points & forbidden scope)", markers: [/设计要点/, /design\s+points/i] },
-  { label: "验收标准 (acceptance criteria)", markers: [/验收标准/, /acceptance\s+criteria/i] },
-  { label: "交付报告格式 (delivery-report format)", markers: [/交付报告格式/, /交付报告/, /delivery[- ]report\s+format/i] },
-]
-
 /** F2 round 合法值（初始轮 / 修正轮——「派单必带」= 无默认值）。
  * 单源：本档为唯一字面量处——schema 面（`agent-tools/subagent.mjs`）与谓词面（本档）同引用（D2）。
  */
 export const ROUND_VALUES = ["initial", "fix"]
 
-/**
- * 五段任务书最小合法样例（F2 契约的正面样例——跨仓测试夹具共用单源；段落名 = 父侧
- * 任务书五段模板）。文本字段判据 = 在场性（内容质量由执行者拒收兜底——需求 §1.14 #9）。
- */
-export const ENG_TASK_BOOK_MIN = [
-  "目标与理由：实现批准设计（夹具任务书——五段文本字段齐备）。",
-  "已知事实：设计已评审通过、token 已签发、批次档在册。",
-  "设计要点与禁止范围：仅落设计档受影响文件清单；禁夹带新语义。",
-  "验收标准：设计档验收标准逐条可机验、项目验证链全绿。",
-  "交付报告格式：交付表 + 文件路径 + 验证命令与结果。",
-].join("\n")
+/** 任务书样例内容（供人照抄；不是门的判据——门只判存在 / 类型 / 非空）：核心四项一份，
+ *  第五项按角色各一份（工程角色 = `designPoints` ∥ explore / plan / coder = `scope`）。 */
+const TASK_BOOK_CORE_MIN = {
+  goal: "实现批准设计（样例任务书——四项核心 + 角色第五项齐备）。",
+  knownFacts: "设计已评审通过、token 已签发、批次档在册。",
+  acceptance: "设计档的验收口径逐条可机验、项目验证链全绿。",
+  reportFormat: "交付表 + 文件路径 + 验证命令与结果。",
+}
+
+/** 工程角色样例（核心四项 + `designPoints`）。 */
+export const ENG_TASK_BOOK_MIN = { ...TASK_BOOK_CORE_MIN, designPoints: "仅落设计档受影响文件清单；禁夹带新语义。" }
+
+/** 非工程角色样例（核心四项 + `scope`）——explore / plan / coder。 */
+export const PLAIN_TASK_BOOK_MIN = { ...TASK_BOOK_CORE_MIN, scope: "只读：相关源 / 设计档；不写任何文件、不碰 bench/。" }
 
 /**
- * F2 任务书六强制字段校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
- * round 枚举（initial|fix，必带集合 = eng-coder/eng-designer）+ 五段文本字段在场。
- * 缺任一 → 抛错（派单缺陷——spawn 机械拒）。scan 面 = args.task ∪ args.context
- * （context 是任务书背景段的携带参数——字段落在任一面均算在场）。
+ * F2 round 结构化参数校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
+ * round 枚举（initial|fix，必带集合 = eng-coder/eng-designer）。
+ * 缺 / 非法 → 抛错（派单缺陷——spawn 机械拒）。
  */
-export function validateTaskBookFields(args) {
+export function validateRoundParam(args) {
   const a = args ?? {}
   const missing = []
   if (!ROUND_VALUES.includes(a.round)) {
@@ -54,17 +42,88 @@ export function validateTaskBookFields(args) {
       ? `round (${ROUND_VALUES.join("|")}) — the structured round parameter`
       : `round ∈ {${ROUND_VALUES.join(", ")}} (got ${JSON.stringify(a.round)})`)
   }
-  const text = [a.context, a.task].filter((s) => typeof s === "string").join("\n")
-  for (const f of TASK_BOOK_FIELDS) {
-    if (!f.markers.some((m) => m.test(text))) missing.push(f.label)
-  }
   if (missing.length === 0) return
   throw new Error(
-    `Engineering spawn task book is missing mandatory field(s): ${missing.join(" · ")}. ` +
-    `The six-field task book — 目标与理由 (goal & why), round (initial|fix), 已知事实 (known facts), ` +
-    `设计要点与禁止范围 (design points & forbidden scope), 验收标准 (acceptance criteria), ` +
-    `交付报告格式 (delivery-report format) — is the spawn contract; a missing field is a dispatch ` +
-    `defect and the spawn is refused.`)
+    `Engineering spawn round gate: ${missing.join(" · ")}. ` +
+    `The spawn contract requires the structured round parameter (initial|fix); ` +
+    `the five task-book parameters are enforced by a separate gate (validateTaskBookParams) — ` +
+    `a missing or invalid round is a dispatch defect and the spawn is refused.`)
+}
+
+/**
+ * F2 任务书名集（**所有 spawn 角色**）：core = 四项核心（全员必带）；fifth = 第五项两名
+ * ——工程角色 = `designPoints` ∥ explore / plan / coder = `scope`。
+ * 单源：本档为唯一名集处——校验 / 拼装 / 探针夹具校验一律经 `taskBookParamsFor(role)` 派生（D2）。
+ * 样例对象 = `ENG_TASK_BOOK_MIN` / `PLAIN_TASK_BOOK_MIN`（供人照抄）。
+ */
+export const TASK_BOOK_PARAMS = {
+  core: ["goal", "knownFacts", "acceptance", "reportFormat"],
+  fifth: { engineering: "designPoints", plain: "scope" },
+}
+
+/** 角色 → 第五项类别（唯一判据；**与模式无关**——工程模式里的 explore 也取 plain）。
+ *  未知角色取 plain：spawn 路径上角色 enum 门先拒收（`agent-tools/subagent.mjs` 的 `ROLES`），到不了本门。 */
+function fifthClassOf(role) {
+  return role === "eng-coder" || role === "eng-designer" ? "engineering" : "plain"
+}
+
+/** 角色 → 该角色的任务书名集（四项核心 + 第五项；序 = 拼装序：第五项插在 `knownFacts` 之后，
+ *  与 C 之前 eng 角色的拼装序逐字相同——审计摘要 marker `/^Design points/i` 不受影响）。 */
+export function taskBookParamsFor(role) {
+  const core = TASK_BOOK_PARAMS.core
+  return [...core.slice(0, 2), TASK_BOOK_PARAMS.fifth[fifthClassOf(role)], ...core.slice(2)]
+}
+
+/** 拼装标签（不导出；仅词面，不是判据——无任何匹配读它）。 */
+const TASK_BOOK_LABELS = {
+  goal: "Goal & why",
+  knownFacts: "Known facts",
+  designPoints: "Design points & forbidden scope",
+  scope: "Scope (what to read / what not to touch)",
+  acceptance: "Acceptance criteria",
+  reportFormat: "Delivery report format",
+}
+
+/**
+ * F2 任务书参数校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）· **所有 spawn 角色**：
+ * 名集按角色取（`taskBookParamsFor(role)`）。判据只有三条——参数存在 ∧ typeof string ∧
+ * trim() 非空。不读内容：无正则、无标题匹配、无双语 marker。缺 / 空白 / 非字符串 → 合并抛，
+ * 文案逐项点名该参数；第五项缺失而另一名在场时，文案附一句指路（只作文案，不加判据）。
+ */
+export function validateTaskBookParams(args, role) {
+  const a = args ?? {}
+  const names = taskBookParamsFor(role)
+  const fifth = TASK_BOOK_PARAMS.fifth[fifthClassOf(role)]
+  const otherFifth = fifth === "designPoints" ? "scope" : "designPoints"
+  const failed = []
+  for (const name of names) {
+    const v = a[name]
+    if (v === undefined || v === null) {
+      const hint = name === fifth && a[otherFifth] !== undefined && a[otherFifth] !== null
+        ? ` (got ${otherFifth} instead — that name belongs to the ${fifthClassOf(role) === "engineering" ? "explore/plan/coder" : "eng-coder/eng-designer"} spawns)`
+        : ""
+      failed.push(`${name} — missing (the task book is four core parameters + the role's fifth)${hint}`)
+    }
+    else if (typeof v !== "string") failed.push(`${name} — must be a string (got ${typeof v})`)
+    else if (v.trim() === "") failed.push(`${name} — blank (trim() is empty)`)
+  }
+  if (failed.length === 0) return
+  throw new Error(
+    `Spawn task-book gate (role='${role}'): ${failed.join(" · ")}. ` +
+    `The task book is four core parameters (${TASK_BOOK_PARAMS.core.join(" / ")}) plus ${fifth} ` +
+    `(the fifth parameter for role='${role}'); a missing, blank or non-string value is a dispatch defect and the spawn is refused.`)
+}
+
+/** 五参 → 子代理任务书文本（**非门禁**，纯拼装）：按 `taskBookParamsFor(role)` 固定序 + 标签，
+ * 空值跳过，`\n\n` 分隔。拼装单源 = 本函数——子代理 input 与探针判官的「任务书全文」同源。 */
+export function composeTaskBookBrief(args, role) {
+  const a = args ?? {}
+  const parts = []
+  for (const name of taskBookParamsFor(role)) {
+    const v = a[name]
+    if (typeof v === "string" && v.trim() !== "") parts.push(`${TASK_BOOK_LABELS[name]}: ${v.trim()}`)
+  }
+  return parts.join("\n\n")
 }
 
 /**

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",