@thincoder/core 0.10.12 → 0.11.1

package/agent-tools/ssh-session.mjs

@@ -2,7 +2,7 @@
  * ssh-session.mjs — SSH 会话面单点（池 ∥ 生命周期 ∥ 动作 ∥ 凭据窗 ∥ 非密预填）。
  * 设计 = `docs/core/design/TOOLS.md` §6.22（D-TO17/D-TO18 · 台账 #1436）；需求 = `docs/core/requirements/TOOLS.md` §4.8。
  * 工具面 = `tools/ssh.mjs`（薄接线）；传输面 = `agent-tools/ssh-transport.mjs`（askpass 链 / 沉降 / 遮蔽 / 帽
- * ——拆档由 = 机制档触 500 顾问线，§6.22 落点表「实施轮先审拆分」）。
+ * ——拆档由 = 机制档触 500 软线，§6.22 落点表「实施轮先审拆分」）。
  *
  * - 池：`_sshSessions`（照 `bash-async.mjs` 池先例——载体经 `carrierField` 吸收）；帽 `SSH_SESSION_MAX = 4`
  *   条存活会话；超限**显式拒**（零静默关旧）。
@@ -30,9 +30,9 @@ import {
 } from "./async-settle.mjs"
 import { assertPoolKeyFree, consumeSubagentToken, nextSubagentId } from "./subagent-scheduler.mjs"
 import {
-  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,
+  SSH_CONNECT_SETTLE_MS, SSH_KEEPALIVE_MS, SSH_RETURN_CAP, SSH_SETTLE_MS, SSH_TIMEOUT_MS, bodyText, capWindow, classifyFailure,
+  createMask, drain, escapeNote, 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"
 
@@ -232,10 +232,11 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
   entry.askpassFile = writeAskpassWrapper(id)
   entry.logStream = createWriteStream(entry.logPath, { flags: "a" })
   entry.logStream.on("error", () => { /* 尽力面 */ })
-  /** 沉降等待（探连 ∥ 带密会话同径）：返回 reason + 已等时长。 */
+  /** 沉降等待（探连 ∥ 带密会话同径）：返回 reason + 已等时长。首屏 = `SSH_CONNECT_SETTLE_MS`（§6.22 ③
+   *  「适用范围」：60 s 只管 `send` / `read` / `secret_input`）；`settleOnSilence` = 首屏沿用静默降级。 */
   const settle = async () => {
     const t0 = Date.now()
-    const reason = await waitSettled(entry, { signal: ctx?.signal ?? null })
+    const reason = await waitSettled(entry, { timeoutMs: SSH_CONNECT_SETTLE_MS, settleOnSilence: true, signal: ctx?.signal ?? null })
     return { reason, waitedMs: Date.now() - t0 }
   }
   /** 起跑（探连 ∥ 带密会话同径；`-i` 两径同带——追加候选身份，不夺既有尝试序列）。
@@ -258,106 +259,48 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
       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("; ")}` }
+      escapeNote(entry), // 半条序列收场注记（§6.22 ③ flush②）——报告一次即清零
+    ].filter(Boolean).map((s) => s.replace(/^\n— /u, ""))
+    return { text: `${statusLine(entry)}\n${bodyText(capWindow(entry, text, SSH_RETURN_CAP))}\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)
-    spawn(effectiveUser, null) // 探连：全会话形 + NumberOfPasswordPrompts=0（不读保存件——铁序）
+  /** 一次尝试（探连 ∥ 带密会话同径）：起跑 + 沉降 + 分类 ⇒ 归一判定（`ok` 假时 `failure` = 可读句）。
+   *  `asUser` 缺省 = 本次有效 user（凭据窗可改）；遮蔽先注册后写入（回显面零泄）。 */
+  const attempt = async (secret = null, asUser = effectiveUser) => {
+    entry.user = asUser ?? null
+    if (secret != null) entry.mask.add(secret)
+    spawn(entry.user, secret)
     let { reason, waitedMs } = await settle()
     // 「已就绪」判据要求进程尚在（静默窗与退出同刻的竞争面——升格一条死连接不成立）。
     if ((reason === "prompt" || reason === "silence") && entry.exitInfo) reason = "exited"
-    if (reason === "aborted") {
-      hardClose(entry, "closed", "consumed")
-      return { error: `ssh connect interrupted before the session was ready (${entry.host})` }
-    }
-    if (reason === "timeout") {
-      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 = classify()
-      if (!cls || cls.kind !== "auth") {
-        const text = failureText(entry, cls)
-        hardClose(entry, "closed", "connect-failed") // 杀树收尾（finalize 只出池——活子进程会成无句柄悬挂）
-        return { error: text }
-      }
-      // 认证类失败 ⇒ **先读保存件**（⑪；有效 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)${failNote ? ` (${failNote}; the credential window was shown)` : ""}` }
-      }
-      if (!String(input.password ?? "").length) {
-        hardClose(entry, "closed", "consumed")
-        return { error: "ssh connect cancelled — an empty password is never submitted (submit a password or cancel the window)" }
-      }
-      entry.user = input.user || effectiveUser || null
-      entry.mask.add(input.password) // 遮蔽先注册后写入（回显面零泄）
-      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") {
-        const cls2 = entry.spawnError ? { message: "ssh client not available" } : classifyFailure(entry.buf)
-        const text = failureText(entry, cls2 ?? { message: "authentication rejected" }, " — the session was not established")
-        // 带密会话未就绪（aborted ∥ timeout）时子进程可能仍活——必走杀树径（否则出池后无句柄可收）。
-        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 (reason === "prompt" || reason === "silence") return { ok: true, reason, waitedMs }
+    const cls = entry.spawnError
+      ? { kind: "spawn", message: `ssh client not available (${entry.spawnError}) — install system OpenSSH or check PATH` }
+      : classifyFailure(entry.buf)
+    const failure = secret == null
+      ? failureText(entry, cls)
+      : failureText(entry, cls ?? { message: "authentication rejected" }, " — the session was not established")
+    return { ok: false, reason, waitedMs, auth: reason === "exited" && cls?.kind === "auth", failure }
+  }
+  try {
+    assertPoolKeyFree(pool, id, "ssh")
+    pool.set(String(id), entry)
+    // 凭据判定单源（D-TO25）：探连 → 密文库 → 凭据窗。本档只提供「一次尝试」，顺序归 resolveSessionSecret。
+    const out = await resolveSessionSecret({
+      ctx, host, port, user: effectiveUser, sessionId: id, offerSave: vaultAvailable(), attempt,
+    })
+    if (out.state !== "ok") {
+      const r = out.r ?? {}
+      const stopped = out.state === "cancel" || out.state === "empty" || (out.phase === "probe" && (r.reason === "aborted" || r.reason === "timeout"))
+      hardClose(entry, "closed", stopped ? "consumed" : "connect-failed")
+      if (out.state === "cancel") {
+        return { error: `ssh connect to ${entry.host} cancelled — no credential was provided (no connection was attempted with one)${out.failNote ? ` (${out.failNote}; the credential window was shown)` : ""}` }
       }
-      if (failNote) flowNotes.unshift(`${failNote}; the credential window was shown`)
-      auth = "password"
+      if (out.state === "empty") return { error: "ssh connect cancelled — an empty password is never submitted (submit a password or cancel the window)" }
+      if (r.reason === "aborted") return { error: `ssh connect interrupted before the session was ready (${entry.host})` }
+      if (r.reason === "timeout") return { error: `ssh connect did not settle within ${SSH_CONNECT_SETTLE_MS}ms (${entry.host}) — the connection is closed; retry or increase the wait${escapeNote(entry)}` }
+      return { error: r.failure }
     }
-    return promote(reason, waitedMs, { auth, extra: flowNotes })
+    return promote(out.r.reason, out.r.waitedMs, { auth: out.source === "key" ? "key" : "password", extra: out.notes })
   } catch (e) {
     hardClose(entry, "closed", "connect-failed") // 异常径同走杀树（子进程可能仍在飞）
     return { error: e?.noUi ? `Error: ${e.message}` : `ssh connect failed: ${e?.message ?? String(e)}` }
@@ -366,8 +309,8 @@ export async function connectSsh(parent, ctx, { host, user, port, label, promptP
   }
 }
 
-/** 缓冲溢出注记（三动作同式——丢弃面显式化；全量恒在 log）。 */
-const droppedNote = (dropped) => (dropped ? "\n— in-memory buffer overflowed — full output in the log" : "")
+/** 丢弃面注记（三动作同式——缓冲溢出 ∥ 半条序列收场；全量恒在 log）。 */
+const droppedNote = (dropped, entry) => `${dropped ? "\n— in-memory buffer overflowed — full output in the log" : ""}${entry ? escapeNote(entry) : ""}`
 
 /** `send`（§6.22 动作表）：不结尾换行 ⇒ 补 `\r`（设备 Enter 语义）；沉降到点返回该轮输出。 */
 export async function sendSsh(parent, ctx, { id, data, settle = true, timeoutMs } = {}) {
@@ -389,11 +332,11 @@ export async function sendSsh(parent, ctx, { id, data, settle = true, timeoutMs
   entry._notify = null
   const { text, dropped } = drain(entry)
   return {
-    text: `${statusLine(entry)}\n${bodyText(capText(text, SSH_RETURN_CAP, entry))}\n— ${settleNote(entry, reason, Date.now() - t0)}${droppedNote(dropped)}`,
+    text: `${statusLine(entry)}\n${bodyText(capWindow(entry, text, SSH_RETURN_CAP))}\n— ${settleNote(entry, reason, Date.now() - t0)}${droppedNote(dropped, entry)}`,
   }
 }
 
-/** `read`：上次读后新增输出（存量即返；无则等至静默/超时——§6.22 ③/⑥）。 */
+/** `read`：上次读后新增输出（**存量即返**、结论 = 缓冲；无存量才等到门① ∥ 门② ∥ 硬超时——§6.22 ③/⑥）。 */
 export async function readSsh(parent, ctx, { id, timeoutMs, maxChars } = {}) {
   const entry = findEntry(parent, id)
   if (!entry) return { error: missingEntry(parent, id) }
@@ -407,11 +350,11 @@ export async function readSsh(parent, ctx, { id, timeoutMs, maxChars } = {}) {
     const reason = await waitSettled(entry, { timeoutMs, signal: ctx?.signal ?? null })
     entry._notify = null
     const { text, dropped } = drain(entry)
-    const body = text ? bodyText(capText(text, cap, entry)) : "(no new output)"
-    return { text: `${statusLine(entry)}\n${body}\n— ${settleNote(entry, reason, Date.now() - t0)}${droppedNote(dropped)}` }
+    const body = text ? bodyText(capWindow(entry, text, cap)) : "(no new output)"
+    return { text: `${statusLine(entry)}\n${body}\n— ${settleNote(entry, reason, Date.now() - t0)}${droppedNote(dropped, entry)}` }
   }
   const { text, dropped } = drain(entry)
-  return { text: `${statusLine(entry)}\n${bodyText(capText(text, cap, entry))}\n— buffered output since the last read${droppedNote(dropped)}` }
+  return { text: `${statusLine(entry)}\n${bodyText(capWindow(entry, text, cap))}\n— buffered output since the last read${droppedNote(dropped, entry)}` }
 }
 
 /** `secret_input`（§6.22 动作表 + ⑦）：凭据窗 → 掩码写入 + `\r`；值永不出现于返回。 */
@@ -441,7 +384,7 @@ export async function secretInputSsh(parent, ctx, { id, label } = {}) {
   entry._notify = null
   const { text, dropped } = drain(entry)
   const tag = label ? ` (${escapeLite(label)})` : ""
-  return { text: `${statusLine(entry)}\nsecret written${tag} — value never echoed\n${bodyText(capText(text, SSH_RETURN_CAP, entry))}\n— ${settleNote(entry, reason, Date.now() - t0)}${droppedNote(dropped)}` }
+  return { text: `${statusLine(entry)}\nsecret written${tag} — value never echoed\n${bodyText(capWindow(entry, text, SSH_RETURN_CAP))}\n— ${settleNote(entry, reason, Date.now() - t0)}${droppedNote(dropped, entry)}` }
 }
 
 /** `close`：stdin 结束 → 1.5 s 宽限 → 杀树；返回末段输出 + 关闭确认。 */
@@ -452,7 +395,7 @@ export async function closeSsh(parent, ctx, { id } = {}) {
   if (entry.state !== "ready") {
     const was = entry.state
     finalize(entry, { state: "closed", status: "consumed" })
-    return { text: `${statusLine(entry)}\n${bodyText(capText(text, SSH_RETURN_CAP, entry))}\n— closed (it was already ${was})` }
+    return { text: `${statusLine(entry)}\n${bodyText(capWindow(entry, text, SSH_RETURN_CAP))}\n— closed (it was already ${was})${droppedNote(dropped, entry)}` }
   }
   entry.closing = true
   try { entry.child.stdin.end() } catch { /* 进程可能已退出——宽限后杀树 */ }
@@ -462,7 +405,7 @@ export async function closeSsh(parent, ctx, { id } = {}) {
   })
   if (!exited) killProcessTree(entry.child)
   finalize(entry, { state: "closed", status: "consumed" })
-  return { text: `${statusLine(entry)}\n${bodyText(capText(text, SSH_RETURN_CAP, entry))}\n— closed${exited ? "" : " (the remote did not exit within 1.5s — the process tree was killed)"}${droppedNote(dropped)}` }
+  return { text: `${statusLine(entry)}\n${bodyText(capWindow(entry, text, SSH_RETURN_CAP))}\n— closed${exited ? "" : " (the remote did not exit within 1.5s — the process tree was killed)"}${droppedNote(dropped, entry)}` }
 }
 
 /** `list`：在活会话清单（id / host / user / 状态 / 空闲秒）——上下文压缩后的恢复路。 */
@@ -482,5 +425,71 @@ 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 落点表候选拆分）。
+// 拆档由 = 机制档触 500 软线，§6.22 落点表候选拆分）。
 export { credentialsSsh, forgetSsh } from "./ssh-vault.mjs"
+// ─── 凭据判定单源（D-TO25：`connect` ∥ 传输面两处共用）─────────────────────────
+
+/**
+ * 凭据判定（§6.22 ⑩ / ⑪ + 裁定 A 预探路）——`connect` 与 `put` / `get` 两处共用的**顺序**：
+ * 探连（密钥 ∥ agent）→ 密文库 → 凭据窗。保存件**恒不先于探连**（S6 / N6 / B7——密钥可用则零读取）。
+ * `attempt(secret, user)` = 调方的起跑 + 沉降 + 分类，回 `{ ok:true, … }` 或 `{ ok:false, auth, failure }`
+ * （`auth` = 服务端拒绝认证 ⇒ 才继续往下一条来源；`failure` = 该来源失败的可读句）。
+ * @returns {Promise<{state:"ok", secret:string|null, user:string|null, source:"key"|"vault"|"window", r:Object, notes:string[]}
+ *   | {state:"fail", phase:"probe"|"vault"|"window", r:Object} | {state:"cancel"|"empty", failNote?:string}>}
+ */
+export async function resolveSessionSecret({ ctx, host, port, user, sessionId, offerSave = false, attempt }) {
+  const notes = []
+  let r = await attempt(null)
+  if (r.ok) return { state: "ok", secret: null, user: user ?? null, source: "key", r, notes }
+  if (!r.auth) return { state: "fail", phase: "probe", r }
+  // 认证类失败 ⇒ **先读保存件**（⑪；有效 user 缺 ⇒ 零消费零删除——直接落窗）。
+  let failNote = ""
+  if (user) {
+    const got = await resolveSecret(host, port, user)
+    if (got.state === "ok") {
+      r = await attempt(got.value, user)
+      if (r.ok) {
+        touchEntry(host, port) // lastUsedAt = 复用成功时更新（写失败 = 增益面静默）
+        return { state: "ok", secret: got.value, user, source: "vault", r, notes: ["saved credential used (no credential window)"] }
+      }
+      if (!r.auth) return { state: "fail", phase: "vault", r }
+      // 条目被服务端拒 ⇒ 删该条目（拒绝即值已失效——避免每次重试旧值）+ 回落窗；删失败时注记如实。
+      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)"
+    } 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 ⇒ 静默（正常首连态）
+  }
+  // 凭据窗（值只走回调返回路 + 子进程环境——NS4：零入参 ∥ 零入结果 ∥ 零落盘）。
+  const input = await askCredential(ctx, { host, user, port, sessionId, offerSave })
+  if (!input) return { state: "cancel", failNote }
+  if (!String(input.password ?? "").length) return { state: "empty" }
+  const asUser = input.user || user || null
+  r = await attempt(input.password, asUser)
+  if (!r.ok) return { state: "fail", phase: "window", r }
+  // 认证成功后才写（opt-in——严格布尔；写失败不影响连接：增益面语义）
+  if (input.save === true && asUser) {
+    const saved = await saveEntry(host, port, { user: asUser, value: input.password })
+    notes.push(saved.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) {
+    notes.push("the credential was not saved (no login user was given for this host)")
+  }
+  if (failNote) notes.unshift(`${failNote}; the credential window was shown`)
+  return { state: "ok", secret: input.password, user: asUser, source: "window", r, notes }
+}
+
+/** 传输面取会话记录（§6.22 ⑬ ②：主机 / 用户 / 端口 / 身份面全取会话记录值——S10「不另填主机 / 凭据」）。
+ *  池查询本档单点（传输件不碰池）；身份面取 ⑨ 记录的 `identityFile`（与 `connect` 同一判定序）。
+ *  `header` = 回执首行的会话冠行（⑬ ③）——形单源仍是 `ssh-transport.mjs` 的 `statusLine`，本档只取一次快照。 */
+export function sessionForTransfer(parent, id) {
+  const entry = findEntry(parent, id)
+  if (!entry) return { error: missingEntry(parent, id) }
+  const rec = lookupHostRecord(entry.host, entry.port)
+  const header = statusLine(entry)
+  return { host: entry.host, user: entry.user ?? null, port: entry.port ?? null, identityFile: rec?.identityFile ?? null, header }
+}

package/agent-tools/ssh-transfer.mjs

@@ -0,0 +1,210 @@
+/**
+ * ssh-transfer.mjs — 传输面单点（`put` / `get` 单文件：系统 `scp` ∥ 凭据链 ∥ 硬超时 ∥ 回执句 ∥ 半截档清理）。
+ * 设计 = `docs/core/design/TOOLS.md` §6.22 ⑬（D-TO24–D-TO27 · 台账 #2026）；需求 = 需求档 §4.8 S10 ∥ S11 ∥ NS8。
+ *
+ * - 执行体 = 系统 `scp`（D-TO24）：缺省 `-O`（经典 SCP 协议——网络设备只实现它），`protocol:"sftp"` 去掉
+ *   `-O`；不自动换协议重试（D-TO27：同笔重试把「协议不对」这个可诊断事实埋在两次尝试之后）。
+ * - 凭据 = 与会话面**同一段判定**（`ssh-session.mjs` 的 `resolveSessionSecret`：探连 → 密文库 → 凭据窗），
+ *   零新凭据通道（D-TO25）；askpass 包装档 / 环境 / 失败分类族全取 `ssh-transport.mjs` 既有导出。
+ * - 内容零入上下文（NS8）：文件字节只经磁盘；回执 = 会话冠行 + 一行状态句，失败时附 stderr 尾段（≤ 600 字符）。
+ * - 本地面（⑬ ②）：本地路径展开 `~`（单源 `expand-home.mjs`）后解析成绝对路径 ⇒ `spawn` 的 `cwd` = 该档
+ *   所在目录、命令行只传**档名**——Windows 盘符的 `:` 与反斜杠都不进 scp 的参数位（scp 以首个 `:`
+ *   切分本地 / 远端）；`get` 的父目录必须已在盘（**零建目录**：建目录即项目内一笔写，绕写门；落点也要
+ *   让人看得见）。
+ * - 回执首行 = 会话状态行冠行（⑬ ③；形单源 = `ssh-transport.mjs` 的 `statusLine`），其下才是状态句
+ *   字面——多设备会话里只给路径，读的人无法确认推到了哪台。
+ * - 不碰会话池：主机 / 用户 / 端口 / 身份面由 `ssh-session.mjs` 的 `sessionForTransfer` 供给。
+ * 模块图：→ ssh-session.mjs（凭据判定 ∥ 会话记录）· ssh-transport.mjs（askpass 链 ∥ 失败分类族 ∥ 冠行）·
+ * tools/process-tree.mjs（树杀）· expand-home.mjs（`~` 展开单源）——叶子向、无环
+ * （`ssh-session.mjs` 不 import 本档）。
+ */
+import { spawn } from "node:child_process"
+import { existsSync, statSync, unlinkSync } from "node:fs"
+import { basename, dirname, resolve } from "node:path"
+import { killProcessTree } from "../tools/process-tree.mjs"
+import { expandHome } from "../expand-home.mjs"
+import {
+  SSH_KEEPALIVE_MS, buildSshEnv, classifyFailure, failureText, statusLine, unlinkAskpass, writeAskpassWrapper,
+} from "./ssh-transport.mjs"
+import { resolveSessionSecret, sessionForTransfer } from "./ssh-session.mjs"
+
+/** 传输硬超时缺省（⑬ ②）：600 000 ms = 选定策略值，非实测（真机读数不符 ⇒ 改这一个数）。 */
+export const SSH_TRANSFER_TIMEOUT_MS = 600_000
+
+/** 夹具缝（⑬「夹具缝」）：`scp` 自有缝——会话侧 `_setSshBinaryForTest` 换不到 `scp`。
+ *  形同 `_setSshBinaryForTest`：setter + `??` 缺省回落 + 用例 `finally` 复位，生产行为零变。 */
+let _scpBinary = null
+let _scpArgPrefix = []
+export function _setScpBinaryForTest(cmd, prefixArgs = []) {
+  _scpBinary = cmd
+  _scpArgPrefix = Array.isArray(prefixArgs) ? prefixArgs : []
+}
+export const scpBinary = () => _scpBinary ?? "scp"
+
+// `~` 展开 = 单源 `thincoder-core/expand-home.mjs`（⑬ ② `localPath` 行；`config.mjs` 已 import 同一件）。
+// 本档不持第二份：两份并存必漂移（D2）。
+
+/** scp 命令形（⑬ ①/②）：`port` / `identityFile` 未给 ⇒ 不下发该选项（让本机配置兜底）。
+ *  **端口开关 = `-P`**（本机 scp 用法行 `[-P port]`）；小写 `-p` 在 scp 是 preserve-times 且**不收值**
+ *  ——与会话面 ssh 的 `-p` 不同，照抄会把这个数字丢成操作数。 */
+function scpArgs({ action, protocol, host, user, port, identityFile, remotePath, localName, keepAliveMs = SSH_KEEPALIVE_MS }) {
+  const keepAliveS = Math.max(1, Math.round((Number(keepAliveMs) || SSH_KEEPALIVE_MS) / 1000))
+  const remote = `${user ? `${user}@` : ""}${host}:${remotePath}`
+  return [
+    ...(protocol === "sftp" ? [] : ["-O"]),
+    "-o", "ConnectTimeout=10",
+    "-o", `ServerAliveInterval=${keepAliveS}`,
+    "-o", "ServerAliveCountMax=4",
+    "-o", "NumberOfPasswordPrompts=1",
+    // 端口开关 = `-P`（scp 原文用法行 `[-P port]`；小写 `-p` 在 scp 是 preserve-times 且**不收值**）——
+    // 与会话面 ssh 的 `-p` 不同，照抄会把这个数字丢成操作数。
+    ...(port ? ["-P", String(port)] : []),
+    ...(identityFile ? ["-i", expandHome(identityFile)] : []),
+    ...(action === "put" ? [localName, remote] : [remote, localName]),
+  ]
+}
+
+/** 起跑一次 scp：stdin 关掉（口令只经 askpass 环境，scp 永不读终端）；到点杀树并留兜底收场。 */
+function runScp({ args, cwd, wrapper, secret, timeoutMs }) {
+  return new Promise((done) => {
+    let child
+    try {
+      child = spawn(scpBinary(), [..._scpArgPrefix, ...args], {
+        cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+        detached: process.platform !== "win32",
+        env: buildSshEnv({ wrapper, secret }),
+      })
+    } catch (e) {
+      done({ spawnError: e?.message ?? String(e) })
+      return
+    }
+    let out = ""
+    let err = ""
+    let settled = false
+    let timedOut = false
+    const finish = (r) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      done({ ...r, out, err, timedOut })
+    }
+    // 到点杀树；子进程不理会 kill 时兜底收场（判据已是 timedOut，不等内层 exit 事件）。
+    const timer = setTimeout(() => {
+      timedOut = true
+      try { killProcessTree(child) } catch { /* 尽力面 */ }
+      setTimeout(() => finish({ code: null, signal: "TIMEOUT" }), 1500).unref?.()
+    }, Math.max(1, timeoutMs))
+    timer.unref?.()
+    child.stdout.on("data", (d) => { out += d })
+    child.stderr.on("data", (d) => { err += d })
+    child.on("error", (e) => finish({ spawnError: e?.message ?? String(e) }))
+    child.on("exit", (code, signal) => finish({ code, signal }))
+  })
+}
+
+const fileSize = (file) => {
+  try { return statSync(file).size } catch { return 0 }
+}
+const fileMtime = (file) => {
+  try { return statSync(file).mtimeMs } catch { return null }
+}
+
+/** 硬超时句（⑬ ⑤）：杀树 + 可读句；**`get` 侧**未删则如实写「落点原样」（不谎称删了），
+ *  **`put` 侧**只如实交底（清远端半截档要第二条通道——本批不做，边界句）。 */
+function timeoutText({ action, label, host, ms, removed = false }) {
+  const secs = Math.round(ms / 100) / 10
+  const base = `Error: ssh transfer timed out after ${secs}s (${label} @ ${host}) — the process tree was killed`
+  if (action !== "get") {
+    return `${base}; the local source file is untouched, and the remote host may keep a partial file (this batch does not clean it)`
+  }
+  return removed
+    ? `${base}; the partial local file was removed (partial local file removed)`
+    : `${base}; the local target was left as it stands (it was not modified since the transfer started)`
+}
+
+/**
+ * `put` / `get` 单文件（§6.22 ⑬）：在会话那台主机上跑一次 `scp`，字节只经磁盘。
+ * @returns {Promise<{ text?: string, error?: string }>}
+ */
+export async function transferSsh(parent, ctx, { action, id, localPath, remotePath, overwrite, protocol, timeoutMs } = {}) {
+  const session = sessionForTransfer(parent, id)
+  if (session.error) return { error: session.error }
+  const sid = String(id ?? "").trim().replace(/^ssh#/i, "")
+  const label = `ssh#${sid}`
+  // 本地面（⑬ ②）：先展开 `~` 再解析成绝对路径——scp 只收档名（盘符 / 反斜杠不进参数位）。
+  const local = resolve(ctx?.cwd ?? process.cwd(), expandHome(localPath))
+  const dir = dirname(local)
+  if (action === "get") {
+    if (!existsSync(dir)) {
+      return { error: `Error: ssh transfer: local directory not found: ${dir} — create it first (this tool never creates one: a mistyped get would land where you cannot see it)` }
+    }
+    if (overwrite !== true && existsSync(local)) {
+      return { error: `Error: ssh transfer: target exists: ${local} — pass overwrite:true to replace it` }
+    }
+  } else if (!existsSync(local)) {
+    return { error: `Error: ssh transfer: local source not found: ${local}` }
+  }
+  const ms = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0 ? Math.floor(Number(timeoutMs)) : SSH_TRANSFER_TIMEOUT_MS
+  // 落点原状（超时清理的判据面）：`null` = 本来没有；否则记字节数与 mtime——**任一变了即视为「本次真被写过」**
+  // （只看尺寸会漏掉「半截档恰好与原档同尺寸」那一支：mtime 一变就补上了）。
+  const pristine = action === "get" && existsSync(local) ? { size: fileSize(local), mtime: fileMtime(local) } : null
+  const wrapper = writeAskpassWrapper(`xfer-${Date.now()}`)
+  /** 一次尝试（凭据判定顺序归 `resolveSessionSecret`；本档只管起跑与判读）。 */
+  const attempt = async (secret, asUser = session.user) => {
+    const argv = scpArgs({
+      action, protocol, host: session.host, user: asUser, port: session.port,
+      identityFile: session.identityFile, remotePath, localName: basename(local),
+    })
+    const r = await runScp({ args: argv, cwd: dir, wrapper, secret, timeoutMs: ms })
+    if (r.spawnError) {
+      return { ok: false, auth: false, reason: "spawn", failure: `Error: scp not available (${r.spawnError}) — install system OpenSSH or check PATH` }
+    }
+    if (r.timedOut) return { ok: false, auth: false, reason: "timeout" }
+    if (r.code === 0) return { ok: true, reason: "ok" }
+    // 认证类失败 ⇒ 判定面继续往下一条凭据来源（密文库 → 凭据窗）；其余失败一律就地交出。
+    const classified = classifyFailure(r.err)
+    const auth = classified?.kind === "auth"
+    const cls = classified ?? { message: `transfer failed (${r.code == null ? `signal ${r.signal ?? "unknown"}` : `exit ${r.code}`})` }
+    // 提示按现场分叉（⑬ ①「不做」行）：已传 `sftp` ⇒ 不再点该参数（用户已用过，点它等于让人重试同一笔）。
+    const hint = protocol === "sftp"
+      ? " — check the remote path; this host may not support file transfer either way"
+      : ' — if that host only speaks SFTP, retry once with protocol:"sftp"'
+    return { ok: false, auth, reason: "exited", failure: failureText({ id: sid, host: session.host, buf: r.err }, cls, hint) }
+  }
+  try {
+    // 凭据窗传 `offerSave: false`：保存面（⑪ 窗内勾选 + `auth` 回写）只在 `connect` 面——传输是既有会话的
+    // 补连接，不是建链入口 ⇒ 传输窗只问 user / password（要存凭据先 `connect` 一次）。设计 ⑬「凭据」段已记此面，
+    // 用户可见后果由描述档写明；判定段仍是同一条（`resolveSessionSecret`）。
+    const out = await resolveSessionSecret({
+      ctx, host: session.host, port: session.port, user: session.user, sessionId: sid, offerSave: false, attempt,
+    })
+    if (out.state !== "ok") {
+      if (out.state === "cancel") return { error: `Error: ssh transfer cancelled — no credential was provided (${label} @ ${session.host})` }
+      if (out.state === "empty") return { error: `Error: ssh transfer cancelled — an empty password is never submitted (${label} @ ${session.host})` }
+      const r = out.r ?? {}
+      if (r.reason === "timeout") {
+        // 半截档清理只限 `get`（`put` 侧本地源档不动——⑬ ⑤ 硬超时行）。只删**半截档**：落点字节数与 mtime
+        // 都没变 ⇒ scp 连文件都没打开就超时，删它等于拿用户的旧档偿命（设计说的是删「半截档」，不是删落点上那个档）。
+        let removed = false
+        if (action === "get" && existsSync(local)) {
+          const touched = pristine === null || fileSize(local) !== pristine.size || fileMtime(local) !== pristine.mtime
+          if (touched) {
+            try { unlinkSync(local); removed = true } catch { /* 尽力面 */ }
+          }
+        }
+        return { error: timeoutText({ action, label, host: session.host, ms, removed }) }
+      }
+      return { error: r.failure ?? `Error: ssh transfer failed (${label} @ ${session.host})` }
+    }
+    const bytes = fileSize(local)
+    const [from, to] = action === "put" ? [localPath, remotePath] : [remotePath, localPath]
+    // 首行 = 会话状态行冠行（⑬ ③）；状态句字面 = 冠行之下那一行（字面单源也定在 ③）。
+    return { text: `${session.header}\n${action} ${from} → ${to} · ${bytes} bytes · exit 0` }
+  } catch (e) {
+    // 工具面契约（`tools/ssh.mjs` 档头）：失败**返回**可读句，不 throw——`askCredential` 在无 UI 端抛
+    // `noUi`（headless / ACP），那条路必须落回回执面（与 `connectSsh` 的 catch 同形）。
+    return { error: e?.noUi ? `Error: ${e.message}` : `Error: ssh transfer failed: ${e?.message ?? String(e)}` }
+  } finally {
+    unlinkAskpass({ askpassFile: wrapper }) // 包装档内容零秘密——收尾尽力面
+  }
+}