dsh-remote 0.8.18 → 0.8.20

package/lib/index.js

@@ -20,33 +20,32 @@
 // Plugin Config MUST be a schemastery schema (zod rejects the undefined row config).
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import ssh2 from 'ssh2'
 import { execFile } from 'node:child_process'
-import zlib from 'node:zlib'
-import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, utimesSync, appendFileSync, unlinkSync, watch } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, appendFileSync, watch } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import iconv from 'iconv-lite'
 
 import {
   shq, normalizeRemotePath, joinRemotePath, remoteDirname, mkdirRemoteDirs,
-  toSftpPath, toShellPath, toDisplayPath, remotePathBase, truncate, shortHash, relPathUnder,
+  toShellPath, toDisplayPath, remotePathBase, truncate, shortHash,
 } from './paths.js'
-import { blobAlgorithm, keyFingerprint } from './hostkey.js'
+import { createHostKeyGuard, isHostKeyKnown as _isHostKeyKnown } from './hostkey.js'
 import { compileIgnore, DEFAULT_IGNORE } from './ignore.js'
 import { friendlyMessage } from './errors.js'
 import { importableEntries, sshConfigPath, readSshConfigText } from './sshconfig.js'
 import { getSecret, deleteSecret, platformBackend, persistPassword } from './credential.js'
 import { syncTree, pushTree, loadSyncState, saveSyncState, pushOneFile } from './sync.js'
-import { searchTree } from './search.js'
-import { resolveMirror, poolKey } from './binding.js'
+import { searchRemote } from './search.js'
+import { resolveMirror, poolKey, lookupSessionCwd, encodeSegmentSafe, readSessionHeaderCwd, requestSessionHint } from './binding.js'
 import { TaskManager } from './tasks.js'
 import { ForwardManager } from './forwards.js'
 import { selfDir, readVersion, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode } from './update.js'
 import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeMachine as _sanitizeMachine, applyMachine as _applyMachine, machineId as _machineId } from './registry.js'
 import { registerHttpTransports } from './http-transport.js'
-
-const { Client } = ssh2
+import { SshPool } from './pool.js'
+import { createFsRoutes } from './routes-fs.js'
+import { removeRemoteTree } from './remote-fs.js'
 
 export const name = 'dsh-remote'
 
@@ -132,33 +131,6 @@ function remoteWorkspacesRoot() {
   return path.join(dshBase(), 'remote-workspaces')
 }
 
-/** Safe path segment for a session id (mirrors DSH's encodeSegment: alnum + _- .).
- *  Session dirs keep the id mostly verbatim; sanitize anything exotic. */
-function encodeSegmentSafe(id) {
-  const s = String(id || '').replace(/[^A-Za-z0-9._-]/g, '_')
-  return s || 'session'
-}
-
-/** Read the cwd from a session log header. Handles plain JSONL, .gz, and
- *  multi-frame zstd (decompress only the first frame, which holds the header).
- *  Returns the header cwd string, or '' when unreadable/absent. */
-function readSessionHeaderCwd(file) {
-  try {
-    let buf = readFileSync(file)
-    if (/\.zstd$/.test(file)) {
-      buf = zlib.zstdDecompressSync(buf)
-    } else if (/\.gz$/.test(file)) {
-      buf = zlib.gunzipSync(buf)
-    }
-    const nl = buf.indexOf(10)
-    if (nl < 0) return ''
-    const head = JSON.parse(buf.subarray(0, nl).toString('utf8'))
-    return typeof head.cwd === 'string' ? head.cwd : ''
-  } catch {
-    return ''
-  }
-}
-
 /** Local mirrors of one remote host. */
 function mirrorRootFor(host, user, port) {
   const tag = [host, user, port].filter(Boolean).join('-').replace(/[^a-zA-Z0-9._-]/g, '_')
@@ -247,550 +219,7 @@ const machineId = _machineId
 // ── host-key registry (TOFU) ──────────────────────────────────────────────
 const KNOWN_HOSTS_FILE = 'known_hosts.json'
 const knownHostsFile = () => path.join(remoteWorkspacesRoot(), KNOWN_HOSTS_FILE)
-
-function loadKnownHosts() {
-  try {
-    const j = JSON.parse(readFileSync(knownHostsFile(), 'utf8'))
-    if (j && typeof j === 'object' && !Array.isArray(j)) return j
-  } catch {}
-  return {}
-}
-
-/** Build an ssh2 `hostVerifier` bound to the current config. */
-function createHostKeyGuard(config) {
-  const id = () => `${config.host}:${config.port}`
-  const mode = config.hostKeyMode === 'verify' || config.hostKeyMode === 'off'
-    ? config.hostKeyMode
-    : 'accept-new'
-  const guard = {
-    mode,
-    lastError: null,
-    knownHosts: loadKnownHosts,
-    forgetHost() {
-      const kh = loadKnownHosts()
-      delete kh[id()]
-      try { mkdirSync(path.dirname(knownHostsFile()), { recursive: true }) } catch {}
-      writeFileSync(knownHostsFile(), JSON.stringify(kh, null, 2))
-    },
-    verifier(key) {
-      if (mode === 'off') return true
-      const fp = keyFingerprint(key)
-      const kh = loadKnownHosts()
-      const stored = kh[id()]
-      if (stored) {
-        if (stored.fingerprint === fp) return true
-        guard.lastError =
-          `host key for ${id()} CHANGED (stored ${stored.fingerprint}, received ${fp}) — ` +
-          'possible man-in-the-middle; run /remote-forget-key to re-trust if this is expected'
-        return false
-      }
-      if (mode === 'verify') {
-        guard.lastError = `unknown host key for ${id()} (hostKeyMode=verify) — trust it first with accept-new`
-        return false
-      }
-      kh[id()] = { algo: blobAlgorithm(key) || (key && key.algo) || 'unknown', fingerprint: fp, firstSeen: new Date().toISOString() }
-      try { mkdirSync(path.dirname(knownHostsFile()), { recursive: true }) } catch {}
-      writeFileSync(knownHostsFile(), JSON.stringify(kh, null, 2))
-      return true
-    },
-  }
-  return guard
-}
-
-/** Whether the current target's key has been recorded/trusted before. */
-function isHostKeyKnown(host, port) {
-  return Object.prototype.hasOwnProperty.call(loadKnownHosts(), `${host}:${port}`)
-}
-
-// ── SSH pool (key / password / agent / keyboard-interactive / proxy) ──────
-
-class SshPool {
-  constructor(config) {
-    this.config = config
-    this.client = null
-    this.connecting = null
-    this.proxyPool = null
-    // Generational token: bumped on every target change / close so a stale
-    // in-flight connect can never hand this pool a connection to an old host.
-    this.epoch = 0
-    /** Auto-detected remote platform: unknown | windows | posix (per target). */
-    this.platform = 'unknown'
-    /** Resolved Git Bash bash.exe path on Windows remotes ('' when none). */
-    this.gitBashPath = ''
-    /** Resolved terminal strategy: native | git-bash. */
-    this.shellMode = 'native'
-    /** In-flight platform detection promise (cached). */
-    this._detecting = null
-    /** Optional async resolver for a machine-stored (keychain) password. */
-    this.passwordResolver = null
-    /** Optional hook called with the live client after a successful connect. */
-    this.onReady = null
-    /** Optional hook called when the pool closes. */
-    this.onCloseHook = null
-  }
-
-  resolveKeyPath() {
-    const p = this.config.privateKeyPath
-    if (!p) return ''
-    if (p.startsWith('~/') || p === '~') return path.join(homedir(), p.slice(1))
-    return p
-  }
-
-  setTarget({ host, port, username, password, privateKeyPath, passphrase, workspace, useAgent, keyboardInteractive, proxy, hostKeyMode }) {
-    if (host !== undefined) this.config.host = String(host)
-    if (port !== undefined && Number(port)) this.config.port = Number(port)
-    if (username !== undefined) this.config.username = String(username)
-    if (password !== undefined && password !== null) this.config.password = String(password)
-    if (privateKeyPath !== undefined) this.config.privateKeyPath = String(privateKeyPath)
-    if (passphrase !== undefined) this.config.passphrase = String(passphrase)
-    if (workspace !== undefined) this.config.workspace = String(workspace)
-    if (useAgent !== undefined) this.config.useAgent = !!useAgent
-    if (keyboardInteractive !== undefined) this.config.keyboardInteractive = !!keyboardInteractive
-    if (proxy !== undefined) this.config.proxy = proxy
-    if (hostKeyMode !== undefined) this.config.hostKeyMode = String(hostKeyMode)
-    // the new target may be a different OS — re-detect on the next command
-    this.platform = 'unknown'
-    this.gitBashPath = ''
-    this.shellMode = 'native'
-    this._detecting = null
-    this.close()
-    return this
-  }
-
-  connect() {
-    if (this.client) return Promise.resolve(this.client)
-    if (this.connecting) return this.connecting
-    const epoch = this.epoch
-    const pending = this._doConnect(epoch)
-    this.connecting = pending
-    const clear = () => {
-      if (this.epoch === epoch && this.connecting === pending) this.connecting = null
-    }
-    pending.then(clear, clear)
-    return pending
-  }
-
-  async _doConnect(epoch) {
-    const isCurrent = () => this.epoch === epoch
-    const guard = createHostKeyGuard(this.config)
-    const client = new Client()
-    let settled = false
-    const fail = (err) => {
-      if (settled) return
-      settled = true
-      if (isCurrent() && this.client === client) this.client = null
-      throw guard.lastError ? new Error(guard.lastError) : err
-    }
-
-    // Proxy jump: SSH to the bastion first, then tunnel to the target through it.
-    let sock = null
-    const proxyCfg = this.config.proxy
-    if (proxyCfg && proxyCfg.host) {
-      try {
-        this.proxyPool = new SshPool({
-          ...this.config,
-          host: proxyCfg.host,
-          port: Number(proxyCfg.port) || 22,
-          username: proxyCfg.username || this.config.username || 'root',
-          password: proxyCfg.password || '',
-          privateKeyPath: proxyCfg.privateKeyPath || '',
-          passphrase: proxyCfg.passphrase || '',
-          proxy: undefined,
-        })
-        const pclient = await this.proxyPool.connect()
-        if (!isCurrent()) throw new Error('ssh target changed during proxy connect')
-        sock = await new Promise((res, rej) => {
-          pclient.forwardOut('127.0.0.1', 0, this.config.host, this.config.port, (e, ch) => (e ? rej(new Error('proxy forward to target failed: ' + ((e && e.message) || e))) : res(ch)))
-        })
-      } catch (err) {
-        return fail(err)
-      }
-    }
-
-    return new Promise((resolve, reject) => {
-      const rejectOnce = (err) => {
-        if (settled) return
-        settled = true
-        if (isCurrent() && this.client === client) this.client = null
-        reject(guard.lastError ? new Error(guard.lastError) : err)
-      }
-      client.on('ready', () => {
-        if (settled) return
-        settled = true
-        if (!isCurrent()) {
-          try { client.end() } catch {}
-          reject(new Error('ssh target changed during connect'))
-          return
-        }
-        this.client = client
-        resolve(client)
-        if (this.onReady) { try { this.onReady(client) } catch {} }
-      })
-      client.on('error', (e) => rejectOnce(e))
-      client.on('close', () => {
-        if (isCurrent() && this.client === client) this.client = null
-        rejectOnce(new Error('ssh connection closed'))
-      })
-
-      const buildOpts = async () => {
-        const opts = {
-          host: this.config.host,
-          port: this.config.port,
-          username: this.config.username,
-          readyTimeout: this.config.connectTimeoutMs,
-          keepaliveInterval: 15000,
-          keepaliveCountMax: 3,
-          hostVerifier: (key) => guard.verifier(key),
-        }
-        if (sock) opts.sock = sock
-        if (this.config.useAgent) {
-          const sockPath = process.env.SSH_AUTH_SOCK
-          if (sockPath) opts.agent = sockPath
-        }
-        let password = this.config.password || ''
-        if (!password && this.passwordResolver) {
-          try { password = (await this.passwordResolver()) || '' } catch {}
-        }
-        if (password) {
-          opts.password = password
-          opts.tryKeyboard = true
-        } else if (this.config.keyboardInteractive && !this.config.privateKeyPath) {
-          opts.tryKeyboard = true
-        }
-        if (this.config.privateKeyPath) {
-          const keyPath = this.resolveKeyPath()
-          if (!keyPath) {
-            throw new Error('no credentials: set a password or a privateKeyPath to connect')
-          }
-          let key
-          try {
-            key = readFileSync(keyPath)
-          } catch (err) {
-            throw new Error(`cannot read private key "${keyPath}": ${err && err.message}`)
-          }
-          opts.privateKey = key
-          opts.passphrase = this.config.passphrase || undefined
-        } else if (!password && !opts.agent) {
-          throw new Error('no credentials: set a password, a privateKeyPath, or enable useAgent to connect')
-        }
-        return opts
-      }
-
-      buildOpts().then(
-        (opts) => {
-          if (opts.tryKeyboard) {
-            client.on('keyboard-interactive', (name, instructions, lang, prompts, finish) => {
-              finish(prompts.map(() => this.config.password || ''))
-            })
-          }
-          client.connect(opts)
-        },
-        (err) => rejectOnce(err),
-      )
-    })
-  }
-
-  /** Detect the remote platform + locate Git Bash once; cached per target. */
-  detect() {
-    if (this.platform !== 'unknown') return Promise.resolve()
-    if (this._detecting) return this._detecting
-    this._detecting = this._detect().finally(() => {
-      this._detecting = null
-    })
-    return this._detecting
-  }
-
-  async _detect() {
-    let res
-    try {
-      // `cmd /c ver` works under cmd.exe, PowerShell AND Git Bash (all print
-      // "Microsoft Windows …"); on POSIX hosts `cmd` simply doesn't exist.
-      res = await this._execRaw('cmd /c ver', { timeoutMs: Math.min(this.config.commandTimeoutMs, 8000) })
-    } catch (err) {
-      this.platform = 'unknown'
-      this.shellMode = 'native'
-      return
-    }
-    const out = String(res.stdout || '') + '\n' + String(res.stderr || '')
-    if (res.code === 0 && /microsoft windows/i.test(out)) {
-      this.platform = 'windows'
-      await this._resolveGitBash()
-      return
-    }
-    // inconclusive — probe for a Git-Bash/MSYS remote (uname prints MINGW64_NT…)
-    try {
-      const u = await this._execRaw('uname -s', { timeoutMs: Math.min(this.config.commandTimeoutMs, 8000) })
-      if (/mingw|msys|cygwin/i.test(String(u.stdout || ''))) {
-        this.platform = 'windows'
-        await this._resolveGitBash()
-        return
-      }
-    } catch {}
-    this.platform = 'posix'
-    this.shellMode = 'native'
-    this.gitBashPath = ''
-  }
-
-  /** On a Windows remote, locate Git Bash (config path → PATH → common installs). */
-  async _resolveGitBash() {
-    const cfg = String(this.config.shell || '').trim()
-    if (cfg && cfg !== 'git-bash' && cfg !== 'native') {
-      if (await this._cmdExists(cfg)) {
-        this.gitBashPath = cfg
-        this.shellMode = 'git-bash'
-        return
-      }
-    }
-    if (cfg === 'native') {
-      this.shellMode = 'native'
-      this.gitBashPath = ''
-      return
-    }
-    try {
-      const r = await this._execRaw('cmd /c where bash', { timeoutMs: 8000 })
-      const first = String(r.stdout || '').trim().split(/\r?\n/)[0].trim()
-      if (first) {
-        this.gitBashPath = first
-        this.shellMode = 'git-bash'
-        return
-      }
-    } catch {}
-    const candidates = [
-      'C:\\Program Files\\Git\\bin\\bash.exe',
-      'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-      ...(process.env.LOCALAPPDATA ? [process.env.LOCALAPPDATA + '\\Programs\\Git\\bin\\bash.exe'] : []),
-      '%LOCALAPPDATA%\\Programs\\Git\\bin\\bash.exe',
-    ]
-    for (const c of candidates) {
-      if (await this._cmdExists(c)) {
-        this.gitBashPath = c
-        this.shellMode = 'git-bash'
-        return
-      }
-    }
-    this.shellMode = 'git-bash' // wanted but not found — commands fall back to raw
-    this.gitBashPath = ''
-  }
-
-  async _cmdExists(p) {
-    try {
-      const r = await this._execRaw(`cmd /c if exist "${p}" (echo Y) else (echo N)`, { timeoutMs: 8000 })
-      return /Y/.test(String(r.stdout || ''))
-    } catch {
-      return false
-    }
-  }
-
-  /** Run one remote command; resolves { code, signal, stdout, stderr }.
-   * On Windows remotes with Git Bash the script is piped to `bash -s` over the
-   * exec-channel stdin — no shell quoting round-trip, so any content (quotes,
-   * backslashes, newlines) survives verbatim. */
-  exec(command, timeoutMsOrOpts) {
-    const opts = timeoutMsOrOpts && typeof timeoutMsOrOpts === 'object' ? timeoutMsOrOpts : { timeoutMs: timeoutMsOrOpts }
-    return this.detect().then(() => {
-      if (this.platform === 'windows' && this.gitBashPath) {
-        const script = String(command)
-        return this._execRaw(`"${this.gitBashPath}" -s`, { ...opts, timeoutMs: opts.timeoutMs || this.config.commandTimeoutMs }, (stream) => {
-          try { stream.end(script) } catch {}
-        })
-      }
-      return this._execRaw(command, opts)
-    })
-  }
-
-  /** Raw exec (no detection / no wrapper). Optional stdinWriter(stream) feeds
-   * the remote process stdin (used by the Git Bash `-s` mode). */
-  _execRaw(command, opts, stdinWriter) {
-    const timeoutMs = (opts && opts.timeoutMs) || this.config.commandTimeoutMs
-    return this.connect().then(
-      (client) =>
-        new Promise((resolve, reject) => {
-          let retried = false
-          const runOn = (c) => {
-            const execOpts = {}
-            if (opts && opts.pty) execOpts.pty = true
-            if (opts && opts.env && typeof opts.env === 'object') execOpts.env = opts.env
-            c.exec(command, execOpts, (err, stream) => {
-              if (err) {
-                // Channel-open failure — or a session termination — usually
-                // means the pooled connection died server-side (idle timeout /
-                // network reset) while keepalive hadn't noticed. Drop it and
-                // retry ONCE on a fresh connection.
-                if (!retried && /channel open failure|open failed|unexpected .* session termination|session termination|disconnect/i.test(String((err && err.message) || err))) {
-                  retried = true
-                  this.invalidate()
-                  return this.connect().then(
-                    (fresh) => runOn(fresh),
-                    (e2) => reject(new Error('ssh exec failed (reconnect): ' + ((e2 && e2.message) || e2))),
-                  )
-                }
-                return reject(new Error('ssh exec failed: ' + ((err && err.message) || err)))
-              }
-              let stdout = ''
-              let stderr = ''
-              let settled = false
-              let exitCode = null
-              let exitSignal = null
-              const hardCap = Math.max(this.config.maxOutputChars * 4, 1024 * 1024)
-              const settle = () => {
-                if (settled) return
-                settled = true
-                clearTimeout(timer)
-                resolve({
-                  code: exitCode,
-                  signal: exitSignal,
-                  stdout: truncate(stdout, this.config.maxOutputChars),
-                  stderr: truncate(stderr, this.config.maxOutputChars),
-                })
-              }
-              const timer = setTimeout(() => {
-                if (settled) return
-                exitCode = -1
-                exitSignal = 'TIMEOUT'
-                // Kill the remote command (SIGTERM) rather than just dropping the
-                // channel, so a runaway process cannot keep running and holding
-                // the SSH connection after we've given up on its output.
-                try {
-                  if (typeof stream.signal === 'function') stream.signal('SIGTERM')
-                } catch {}
-                const hardClose = setTimeout(() => {
-                  try { stream.close() } catch {}
-                }, 800)
-                if (typeof hardClose.unref === 'function') hardClose.unref()
-                settle()
-              }, timeoutMs)
-              stream.on('close', (code, signal) => {
-                if (settled) return
-                exitCode = code
-                exitSignal = signal
-                settle()
-              })
-              stream.on('data', (d) => {
-                if (stdout.length < hardCap) stdout += d
-              })
-              stream.stderr.on('data', (d) => {
-                if (stderr.length < hardCap) stderr += d
-              })
-              stream.on('error', (e) => {
-                if (settled) return
-                settled = true
-                clearTimeout(timer)
-                reject(new Error('ssh stream error: ' + ((e && e.message) || e)))
-              })
-              if (stdinWriter) {
-                try { stdinWriter(stream) } catch {}
-              }
-            })
-          }
-          runOn(client)
-        }),
-    )
-  }
-
-  /** Resolve a promisified SFTP client. All paths normalized via toSftpPath(). */
-  sftp() {
-    return this.connect().then(
-      (client) =>
-        new Promise((resolve, reject) => {
-          let retried = false
-          const runOn = (c) => {
-            c.sftp((err, sftp) => {
-              if (err) {
-                // Same dead-connection recovery as exec(): a channel open
-                // failure — or a session termination (remote closed the
-                // SFTP subchannel, e.g. transient network blip / sshd idle
-                // drop) — means the pooled connection is stale: drop it and
-                // retry ONCE on a fresh connection.
-                if (!retried && /channel open failure|open failed|unexpected sftp session termination|session termination|disconnect/i.test(String((err && err.message) || err))) {
-                  retried = true
-                  this.invalidate()
-                  return this.connect().then(
-                    (fresh) => runOn(fresh),
-                    (e2) => reject(new Error('ssh sftp failed (reconnect): ' + ((e2 && e2.message) || e2))),
-                  )
-                }
-                return reject(new Error('ssh sftp failed: ' + ((err && err.message) || err)))
-              }
-              const withTimeout = (fn) => (...args) =>
-                new Promise((r2, j2) => {
-                  const timer = setTimeout(() => j2(new Error('sftp operation timed out')), this.config.commandTimeoutMs)
-                  const done = (e, v) => {
-                    clearTimeout(timer)
-                    e ? j2(e) : r2(v)
-                  }
-                  try { fn(...args, done) } catch (e) { clearTimeout(timer); j2(e) }
-                })
-              const P = (p) => toSftpPath(p)
-              resolve({
-                readdir: (dir) => withTimeout((d, cb) => sftp.readdir(d, cb))(P(dir)),
-                stat: (p) => withTimeout((d, cb) => sftp.stat(d, cb))(P(p)),
-                lstat: (p) => withTimeout((d, cb) => sftp.lstat(d, cb))(P(p)),
-                mkdir: (dir) => withTimeout((d, cb) => sftp.mkdir(d, cb))(P(dir)),
-                rmdir: (dir) => withTimeout((d, cb) => sftp.rmdir(d, cb))(P(dir)),
-                unlink: (p) => withTimeout((d, cb) => sftp.unlink(d, cb))(P(p)),
-                rename: (p, d) => withTimeout((a, b, cb) => sftp.rename(a, b, cb))(P(p), P(d)),
-                realpath: (p) => withTimeout((d, cb) => sftp.realpath(d, cb))(P(p)),
-                readFile: (p) => withTimeout((d, cb) => sftp.readFile(d, cb))(P(p)),
-                writeFile: (p, data) => withTimeout((d, data2, cb) => sftp.writeFile(d, data2, cb))(P(p), data),
-                fastGet: (p, lp) => withTimeout((d, l, cb) => sftp.fastGet(d, l, cb))(P(p), lp),
-                fastPut: (lp, p) => withTimeout((l, d, cb) => sftp.fastPut(l, d, cb))(lp, P(p)),
-              })
-            })
-          }
-          runOn(client)
-        }),
-    )
-  }
-
-  /**
-   * Drop the cached client and force a fresh connection on the next call.
-   * Called when a channel open fails (e.g. "Channel open failure: open
-   * failed") — the pooled SSH connection is usually dead server-side while
-   * keepalive has not yet noticed, and reusing it keeps failing. The epoch
-   * bump orphans any in-flight connect; the client is ended so ssh2 frees
-   * its sockets.
-   */
-  invalidate() {
-    this.epoch++
-    const client = this.client
-    this.client = null
-    const pending = this.connecting
-    this.connecting = null
-    if (pending && typeof pending.catch === 'function') {
-      try { pending.catch(() => {}) } catch {}
-    }
-    if (this.proxyPool) {
-      try { this.proxyPool.close() } catch {}
-      this.proxyPool = null
-    }
-    if (client) {
-      try { client.end() } catch {}
-    }
-  }
-
-  close() {
-    this.epoch++
-    const client = this.client
-    this.client = null
-    const pending = this.connecting
-    this.connecting = null
-    if (pending && typeof pending.catch === 'function') {
-      try { pending.catch(() => {}) } catch {}
-    }
-    if (this.proxyPool) {
-      try { this.proxyPool.close() } catch {}
-      this.proxyPool = null
-    }
-    if (client) {
-      try {
-        client.end()
-      } catch {}
-    }
-    if (this.onCloseHook) {
-      try { this.onCloseHook() } catch {}
-    }
-  }
-}
+const isHostKeyKnown = (host, port) => _isHostKeyKnown(knownHostsFile(), host, port)
 
 // ── encoding helpers ───────────────────────────────────────────────────────
 
@@ -806,7 +235,7 @@ function encodeText(s, enc) {
 // ── apply ─────────────────────────────────────────────────────────────────
 
 export async function apply(ctx, config) {
-  const pool = new SshPool(config)
+  const pool = new SshPool(config, { knownHostsFile })
   ctx.effect(() => () => pool.close(), 'dsh-remote.close')
 
   migrateLegacyData()
@@ -953,7 +382,7 @@ export async function apply(ctx, config) {
       // session passes its own mirror-resolved remote path explicitly.
       workspace: '',
     })
-    const created = new SshPool(poolConfig)
+    const created = new SshPool(poolConfig, { knownHostsFile })
     // Keychain-backed passwords resolve against THIS pool's machine record.
     created.passwordResolver = async () => machinePassword(rec || { id: '', password: poolConfig.password })
     machinePools.set(key, created)
@@ -1126,7 +555,7 @@ export async function apply(ctx, config) {
     const state = loadSyncState(localDir)
     const next = { ...state }
     if (rels.includes('*')) {
-      const r = await pushTree(sftp, localDir, ws, { maxFiles: 500, maxFileBytes: config.maxFileBytes, isIgnored: matcher, state: next })
+      const r = await pushTree(sftp, localDir, ws, { maxFiles: 2000, maxFileBytes: config.maxFileBytes, isIgnored: matcher, state: next })
       Object.assign(next, r.nextState)
       for (const c of r.stats.conflicts) audit('auto-push-conflict', `push ${c.path}`, 1, machine)
     } else {
@@ -1182,88 +611,6 @@ export async function apply(ctx, config) {
     return text
   }
 
-  /** Structured listing: name + type + size + mtime + mode (SFTP protocol-level,
-   * works on any remote: POSIX / cmd.exe / PowerShell). */
-  const listDirStructured = async (p, sshPool = pool) => {
-    const target = normalizeRemotePath(p || '/')
-    let sftp
-    try {
-      sftp = await sshPool.sftp()
-    } catch (err) {
-      throw new Error('browse failed: ' + ((err && err.message) || err))
-    }
-    let list
-    try {
-      list = await sftp.readdir(target)
-    } catch (err) {
-      // Missing directory / deleted folder: not an internal error. Report it
-      // distinctly so the UI can show「目录不存在」without treating it as a
-      // hard failure (500) that collapses the whole tree.
-      const msg = String((err && err.message) || err)
-      if (/no such file|not found|does not exist|ENOENT/i.test(msg)) {
-        return { path: target, items: [], missing: true }
-      }
-      throw new Error('browse failed: ' + msg)
-    }
-    const items = []
-    const symIdx = []
-    for (const e of list) {
-      const name = String(e.filename)
-      if (name === '.' || name === '..' || !name) continue
-      const a = e.attrs || {}
-      let type
-      if (a.isSymbolicLink && a.isSymbolicLink()) {
-        type = 'symlink'
-        symIdx.push(items.length)
-      } else if (a.isDirectory && a.isDirectory()) {
-        type = 'dir'
-      } else {
-        type = 'file'
-      }
-      items.push({
-        type,
-        name,
-        size: typeof a.size === 'number' ? a.size : 0,
-        mtime: typeof a.mtime === 'number' ? a.mtime : 0,
-        mode: typeof a.mode === 'number' ? a.mode.toString(8) : '',
-      })
-    }
-    // Resolve symlink-to-dir vs symlink-to-file (bounded, failure-tolerant).
-    if (symIdx.length) {
-      await Promise.all(symIdx.map(async (i) => {
-        const full = joinRemotePath(target, items[i].name)
-        try {
-          const st = await sftp.lstat(full)
-          items[i].type = st && st.isDirectory && st.isDirectory() ? 'dir' : 'file'
-        } catch { /* degrade to file */ }
-      }))
-    }
-    return { path: target, items }
-  }
-
-  /** Windows drive letters as display-form dir entries (the "This PC" root view).
-   * `cmd /c fsutil fsinfo drives` works under cmd/PowerShell/Git Bash and prints
-   * e.g. "Drives: C:\\ D:\\ E:\\"; falls back to listing Git-Bash mount points
-   * (/c /d …). Returns [] on POSIX hosts or when enumeration fails. */
-  const listRemoteDrives = async () => {
-    let letters = []
-    try {
-      const res = await pool.exec('cmd /c fsutil fsinfo drives', { timeoutMs: Math.min(config.commandTimeoutMs, 8000) })
-      letters = [...String(res.stdout || '').matchAll(/([a-zA-Z]):\\?/g)].map((mm) => mm[1].toUpperCase())
-    } catch {}
-    if (!letters.length) {
-      try {
-        const res = await pool.exec('ls -d /[a-z] 2>/dev/null', { timeoutMs: Math.min(config.commandTimeoutMs, 8000) })
-        letters = String(res.stdout || '')
-          .split(/\s+/)
-          .map((s) => s.replace(/^\/+|\/+$/g, ''))
-          .filter((s) => /^[a-zA-Z]$/.test(s))
-          .map((s) => s.toUpperCase())
-      } catch {}
-    }
-    return [...new Set(letters)].sort().map((l) => ({ name: l + ':\\', path: l + ':\\', type: 'dir', drive: true, size: 0, mtime: 0 }))
-  }
-
   const isRemoteDir = async (p, sshPool = pool) => {
     const target = normalizeRemotePath(p)
     try {
@@ -1275,30 +622,6 @@ export async function apply(ctx, config) {
     }
   }
 
-  /** Recursive remote delete (bounded): unlink files bottom-up, then rmdir. */
-  const removeRemoteTree = async (sftp, p, maxFiles = 2000) => {
-    let removed = 0
-    const walk = async (dir) => {
-      if (removed >= maxFiles) return
-      let entries = []
-      try { entries = (await sftp.readdir(dir)) || [] } catch { return }
-      for (const e of entries) {
-        if (removed >= maxFiles) return
-        const name = String(e.filename)
-        if (name === '.' || name === '..') continue
-        const fp = joinRemotePath(dir, name)
-        const isDir = !!(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory())
-        if (isDir) await walk(fp)
-        else {
-          try { await sftp.unlink(fp); removed++ } catch {}
-        }
-      }
-      try { await sftp.rmdir(dir); removed++ } catch { /* already gone or non-empty */ }
-    }
-    await walk(p)
-    return removed
-  }
-
   // ── remote workspace state ────────────────────────────────────────────────
   const wsPath = () => (config.workspace || '').trim()
   /** Map a LOCAL path to the remote path its mirror represents ('' when the
@@ -1323,22 +646,66 @@ export async function apply(ctx, config) {
    *  with several live sessions the "first" one is arbitrary and may belong to
    *  another machine. Tool calls must never route through this — they resolve
    *  their own session through `bindingFor()`, which is authoritative. */
-  const sessionRemotePath = (sessionId) => {
-    let cwd = ''
+  const sessionsSvc = () => (ctx && typeof ctx.get === 'function' ? ctx.get('sessions') : null)
+  const sessionCwd = (sessionId) => {
+    const sessions = sessionsSvc()
+    if (sessionId) return lookupSessionCwd(sessionId, { sessions, dshHome: dshBase() })
     try {
-      const sessions = ctx && typeof ctx.get === 'function' ? ctx.get('sessions') : null
-      if (sessions && typeof sessions.get === 'function' && sessionId) {
-        const s = sessions.get(sessionId)
-        if (s && s.header && s.header.cwd) cwd = String(s.header.cwd)
-      } else if (sessions && typeof sessions.list === 'function') {
+      if (sessions && typeof sessions.list === 'function') {
         const s = sessions.list()[0]
-        if (s && s.header && s.header.cwd) cwd = String(s.header.cwd)
+        if (s && s.header && s.header.cwd) return String(s.header.cwd)
       }
     } catch { /* sessions service unavailable */ }
+    return ''
+  }
+  const sessionRemotePath = (sessionId) => {
+    const cwd = sessionCwd(sessionId)
     if (!cwd) return ''
     return resolveMirrorForLocal(cwd).remotePath
   }
 
+  /**
+   * HTTP binding for sidebar file routes. A sessionId/local hint is authoritative:
+   * a local (non-mirror) session is refused rather than falling back to the
+   * active machine. Requests with no hint keep the picker/settings active pool.
+   */
+  const resolveRequestBinding = async (req, body = {}) => {
+    const hint = requestSessionHint(req, body)
+    let cwd = hint.local
+    if (!cwd && hint.sessionId) cwd = lookupSessionCwd(hint.sessionId, { sessions: sessionsSvc(), dshHome: dshBase() })
+    if (cwd) {
+      const { remotePath, machine, mirrorDir } = resolveMirrorForLocal(cwd)
+      if (remotePath && machine) {
+        return {
+          pool: poolForMachine(machine),
+          ws: remotePath,
+          host: machine.host,
+          username: machine.username,
+          port: machine.port,
+          mirrorDir,
+          bound: true,
+          local: false,
+        }
+      }
+      const err = new Error(
+        'this session is LOCAL — its workspace is not a remote mirror, so there is no remote host to act on. '
+        + 'Refusing rather than falling back to the active machine.',
+      )
+      err.httpStatus = 403
+      throw err
+    }
+    return {
+      pool,
+      ws: wsPath(),
+      host: config.host,
+      username: config.username,
+      port: config.port,
+      mirrorDir: wsPath() ? mirrorDirFor(wsPath(), config.host, config.username, config.port) : null,
+      bound: false,
+      local: false,
+    }
+  }
+
   // ── session-bound remote binding (the authoritative tool path) ─────────────
 
   /**
@@ -1634,8 +1001,8 @@ export async function apply(ctx, config) {
       description:
         'Download the current remote workspace into its local mirror directory over SFTP (bounded, three-way conflict-aware). Makes the remote files visible/editable locally so the DSH native workspace / fs tools can operate on them. Conflicts (both sides modified) are reported and never overwritten; use force=true to override.',
       parameters: {
-        depth: { type: 'integer', description: 'Max directory depth to mirror (default 5)' },
-        maxFiles: { type: 'integer', description: 'Max files to download (default 500)' },
+        depth: { type: 'integer', description: 'Max directory depth to mirror (default 8)' },
+        maxFiles: { type: 'integer', description: 'Max files to download (default 2000)' },
         dryRun: { type: 'boolean', description: 'Compute the plan without downloading (default false)' },
         force: { type: 'boolean', description: 'Overwrite conflicting files (default false)' },
         async: { type: 'boolean', description: 'Run in the background and return a task id (default false)' },
@@ -1646,8 +1013,8 @@ export async function apply(ctx, config) {
         const p = b.ws
         const local = b.mirrorDir || mirrorDirFor(p, b.host, b.username, b.port)
         mkdirSync(local, { recursive: true })
-        const depth = Math.min(Math.max(Number(args.depth) || 5, 1), 8)
-        const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
+        const depth = Math.min(Math.max(Number(args.depth) || 8, 1), 16)
+        const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 2000, 1), 20000)
         const isIgnored = ignoreMatcher()
         const body = { depth, maxFiles, dryRun: !!args.dryRun, force: !!args.force, isIgnored }
         const runSync = async () => {
@@ -1660,7 +1027,8 @@ export async function apply(ctx, config) {
           const state = loadSyncState(local)
           const { stats, nextState } = await syncTree(sftp, p, local, { ...body, state, maxFileBytes: config.maxFileBytes })
           if (!args.dryRun) saveSyncState(local, nextState)
-          let text = `${args.dryRun ? 'WOULD download' : 'Downloaded'} ${stats.files} file(s) from ${p} → ${local}${stats.files >= maxFiles ? ' (hit download cap)' : ''}.`
+          let text = `${args.dryRun ? 'WOULD download' : 'Downloaded'} ${stats.files} file(s) from ${p} → ${local}.`
+          if (stats.truncated || stats.files >= maxFiles) text += ` TRUNCATED (hit depth=${depth} or maxFiles=${maxFiles} cap; raise maxFiles/depth and re-run).`
           if (stats.skippedUnchanged) text += ` ${stats.skippedUnchanged} unchanged.`
           if (stats.skippedLarge) text += ` ${stats.skippedLarge} too large (over ${config.maxFileBytes} bytes).`
           if (stats.staleRemote) text += ` ${stats.staleRemote} remote entries gone (kept locally; use rw_push to mirror deletions).`
@@ -1685,7 +1053,7 @@ export async function apply(ctx, config) {
       description:
         'Upload the local mirror of the current remote workspace back to the remote host over SFTP (bounded, three-way conflict-aware). Use after editing files in the local mirror so the remote reflects your changes. Conflicts (both sides modified) are reported and never overwritten; use force=true to override.',
       parameters: {
-        maxFiles: { type: 'integer', description: 'Max files to upload (default 500)' },
+        maxFiles: { type: 'integer', description: 'Max files to upload (default 2000)' },
         dryRun: { type: 'boolean', description: 'Compute the plan without uploading (default false)' },
         force: { type: 'boolean', description: 'Overwrite conflicting files (default false)' },
         async: { type: 'boolean', description: 'Run in the background and return a task id (default false)' },
@@ -1696,7 +1064,7 @@ export async function apply(ctx, config) {
         const p = b.ws
         const local = b.mirrorDir || mirrorDirFor(p, b.host, b.username, b.port)
         if (!existsSync(local)) throw new Error(`rw_push: local mirror does not exist — run rw_sync first (${local})`)
-        const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
+        const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 2000, 1), 20000)
         const isIgnored = ignoreMatcher()
         const body = { maxFiles, dryRun: !!args.dryRun, force: !!args.force, isIgnored }
         const runPush = async () => {
@@ -1710,6 +1078,7 @@ export async function apply(ctx, config) {
           const { stats, nextState } = await pushTree(sftp, local, p, { ...body, state, maxFileBytes: config.maxFileBytes })
           if (!args.dryRun) saveSyncState(local, nextState)
           let text = `${args.dryRun ? 'WOULD upload' : 'Uploaded'} ${stats.files} file(s) from ${local} → ${p}.`
+          if (stats.truncated || stats.files >= maxFiles) text += ` TRUNCATED (hit maxFiles=${maxFiles} cap; raise maxFiles and re-run).`
           if (stats.skippedUnchanged) text += ` ${stats.skippedUnchanged} unchanged.`
           if (stats.skippedLarge) text += ` ${stats.skippedLarge} too large (over ${config.maxFileBytes} bytes).`
           if (stats.staleLocal) text += ` ${stats.staleLocal} local entries gone remotely (kept remotely; use rw_remove to mirror deletions).`
@@ -2058,7 +1427,7 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_search',
       description:
-        'Search remote files for a pattern (recursive SFTP walk — works on ANY remote including Windows, honors ignore rules). Returns matching file:line rows; output is capped.',
+        'Search remote files for a pattern. POSIX remotes try `rg` then `grep -R` first; Windows and fallbacks use a portable SFTP walk. Honors ignore rules. Returns matching file:line rows; output is capped.',
       parameters: {
         pattern: { type: 'string', required: true, description: 'Pattern to search for (extended regex)' },
         path: { type: 'string', description: 'Directory to search (default: current remote workspace)' },
@@ -2081,16 +1450,18 @@ export async function apply(ctx, config) {
         } catch (err) {
           throw new Error('rw_search: bad pattern: ' + ((err && err.message) || err))
         }
-        const sftp = await b.pool.sftp()
         const maxMatches = Math.min(Math.max(Number(args.maxMatches) || 500, 1), 2000)
         const matcher = ignoreMatcher()
-        const { matches, scanned, truncated } = await searchTree(sftp, dir, {
+        const { matches, scanned, truncated } = await searchRemote(b.pool, dir, {
+          pattern,
           regex,
           glob: args.glob,
+          ignoreCase: args.ignoreCase !== false,
           contextLines: Math.min(Math.max(Number(args.contextLines) || 0, 0), 10),
           maxMatches,
           maxScanBytes: Math.min(config.maxFileBytes || 1024 * 1024, 1024 * 1024),
           isIgnored: (name, isDir) => matcher(name, isDir),
+          timeoutMs: config.commandTimeoutMs,
         })
         if (!matches.length) return { text: `no matches for /${pattern}/ in ${dir} (${scanned} files scanned)` }
         let text = matches.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n')
@@ -2282,7 +1653,7 @@ export async function apply(ctx, config) {
       name: 'remote-forget-key',
       description: 'Drop the trusted host-key record for the current machine so the next connect re-records it.',
       handler: () => {
-        createHostKeyGuard(config).forgetHost()
+        createHostKeyGuard(config, knownHostsFile()).forgetHost()
         return { kind: 'success', text: `forgot host key for ${config.host || '<none>'}:${config.port} — the next connect will re-record it.` }
       },
     })
@@ -2426,7 +1797,25 @@ export async function apply(ctx, config) {
           const sessionId = q.get('sessionId') ? decodeURIComponent(q.get('sessionId')) : ''
           // Per-session remote context (issue #13): when a sessionId is given,
           // sessionMode reflects THAT session's cwd, not the machine default.
-          return sendJson(res, 200, sessionId ? { ...status(), sessionMode: sessionRemotePath(sessionId) ? 'remote' : 'local', sessionRemotePath: sessionRemotePath(sessionId) } : status())
+          if (!sessionId) return sendJson(res, 200, status())
+          const cwd = sessionCwd(sessionId)
+          const resolved = cwd ? resolveMirrorForLocal(cwd) : { remotePath: '', machine: null }
+          const extra = {
+            sessionMode: resolved.remotePath ? 'remote' : 'local',
+            sessionRemotePath: resolved.remotePath || '',
+            sessionBound: !!(resolved.machine && resolved.remotePath),
+          }
+          if (resolved.machine && resolved.remotePath) {
+            const p = poolForMachine(resolved.machine)
+            extra.host = resolved.machine.host
+            extra.username = resolved.machine.username
+            extra.port = resolved.machine.port
+            extra.workspace = toDisplayPath(resolved.remotePath, p.platform)
+            // Bound sessions are allowed to list/read even if this process has
+            // not yet opened a socket — /ls connects on demand.
+            extra.connected = true
+          }
+          return sendJson(res, 200, { ...status(), ...extra })
         }
         sendJson(res, 405, { error: 'method not allowed' })
       },
@@ -2557,219 +1946,10 @@ export async function apply(ctx, config) {
         }
       },
     },
-    {
-      kind: 'exact',
-      path: '/dsh-remote/ls',
-      handler: async (req, res) => {
-        try {
-          await pool.detect()
-          const q = new URL(req.url, 'http://localhost').searchParams
-          const raw = q.get('path') ? decodeURIComponent(q.get('path')) : wsPath()
-          const canon = normalizeRemotePath(raw)
-          const win = pool.platform === 'windows'
-          // Windows root → "This PC" drive view (C:\ D:\ E:\), not the Git-Bash
-          // MSYS root. When the platform probe was inconclusive we still try — a
-          // real Windows box answers fsutil, a POSIX box yields no letters and
-          // falls through to the normal root listing.
-          if (canon === '/' || raw === '' || raw === '/') {
-            if (win || pool.platform !== 'posix') {
-              const drives = await listRemoteDrives()
-              if (drives.length) return sendJson(res, 200, { path: '', platform: 'windows', items: drives })
-            }
-            if (win) return sendJson(res, 200, { path: '', platform: 'windows', items: [] })
-          }
-          const out = await listDirStructured(canon)
-          const items = out.items.map((it) => ({
-            ...it,
-            // full display-form path so the client never joins paths itself
-            path: toDisplayPath(joinRemotePath(canon, it.name), pool.platform),
-          }))
-          return sendJson(res, 200, { path: toDisplayPath(out.path, pool.platform), platform: win ? 'windows' : 'posix', items })
-        } catch (err) {
-          return sendJson(res, 500, { error: String((err && err.message) || err) })
-        }
-      },
-    },
-    {
-      // Read a remote file over SFTP (live). Text returns as content (CRLF→LF,
-      // encoding-aware), binary is reported with size+head (base64). A stat
-      // happens first; oversized files are previewed from a streamed head chunk
-      // instead of being fully buffered.
-      kind: 'exact',
-      path: '/dsh-remote/read',
-      handler: async (req, res) => {
-        if (req.method !== 'GET' && req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
-        try {
-          const q = new URL(req.url, 'http://localhost').searchParams
-          let p = q.get('path') ? decodeURIComponent(q.get('path')) : ''
-          let encoding = ''
-          let maxBytes = 256 * 1024
-          if (req.method === 'POST') {
-            const body = JSON.parse((await readBody(req)) || '{}')
-            if (!p) p = String(body.path || '')
-            if (body.encoding) encoding = String(body.encoding)
-            if (body.maxBytes) maxBytes = Number(body.maxBytes)
-          }
-          if (q.get('maxBytes')) maxBytes = Number(q.get('maxBytes'))
-          if (!p) return sendJson(res, 400, { ok: false, error: 'path is required' })
-          const target = normalizeRemotePath(p)
-          maxBytes = Math.min(Math.max(Number(maxBytes) || 256 * 1024, 1024), 2 * 1024 * 1024)
-          let sftp
-          try {
-            sftp = await pool.sftp()
-          } catch (err) {
-            return sendJson(res, 500, { ok: false, error: 'sftp unavailable: ' + ((err && err.message) || err) })
-          }
-          let st
-          try { st = await sftp.stat(target) } catch (err) {
-            return sendJson(res, 500, { ok: false, error: 'read failed: ' + ((err && err.message) || err) })
-          }
-          if (st.size > maxBytes) {
-            // Head preview for oversized files: fastGet to a temp file, read the
-            // first maxBytes, delete the temp. Never buffers the whole file.
-            const tmp = path.join(dshBase(), '.dsh-remote-preview-' + process.pid)
-            try {
-              await sftp.fastGet(target, tmp)
-              const { open } = await import('node:fs/promises')
-              const fd = await open(tmp, 'r')
-              const head = Buffer.alloc(Math.min(maxBytes, st.size))
-              await fd.read(head, 0, head.length, 0)
-              await fd.close()
-              try { unlinkSync(tmp) } catch {}
-              const content = decodeBuf(head, encoding || config.encoding).replace(/\r\n/g, '\n')
-              return sendJson(res, 200, { ok: true, binary: false, content, truncated: true, size: st.size })
-            } catch (err) {
-              return sendJson(res, 500, { ok: false, error: 'read failed: ' + ((err && err.message) || err) })
-            }
-          }
-          let buf
-          try {
-            buf = await sftp.readFile(target)
-          } catch (err) {
-            return sendJson(res, 500, { ok: false, error: 'read failed: ' + ((err && err.message) || err) })
-          }
-          const headN = Math.min(buf.length, 8192)
-          let binary = false
-          for (let i = 0; i < headN; i++) {
-            if (buf[i] === 0) { binary = true; break }
-          }
-          if (binary) {
-            return sendJson(res, 200, { ok: true, binary: true, size: buf.length, head: buf.slice(0, Math.min(buf.length, 4096)).toString('base64') })
-          }
-          let content = decodeBuf(buf, encoding || config.encoding).replace(/\r\n/g, '\n')
-          const truncated = content.length > maxBytes
-          if (truncated) content = content.slice(0, maxBytes) + `\n…[truncated: ${buf.length - maxBytes} more bytes]`
-          return sendJson(res, 200, { ok: true, binary: false, content, truncated })
-        } catch (err) {
-          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
-        }
-      },
-    },
-    {
-      // Write a remote file (sidebar editor save). `expectedMtime` is an
-      // optimistic lock: a 409 is returned when the remote changed meanwhile.
-      kind: 'exact',
-      path: '/dsh-remote/write',
-      handler: async (req, res) => {
-        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
-        try {
-          const body = JSON.parse((await readBody(req)) || '{}')
-          const p = normalizeRemotePath(String(body.path || ''))
-          if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path is required' })
-          const sftp = await pool.sftp()
-          let st = null
-          try { st = await sftp.stat(p) } catch { /* new file */ }
-          if (body.expectedMtime != null && st && st.mtime !== Number(body.expectedMtime)) {
-            return sendJson(res, 409, { ok: false, error: `远端文件已变化（mtime ${st.mtime} ≠ ${body.expectedMtime}），已放弃保存——请重新读取后再编辑` })
-          }
-          const buf = encodeText(String(body.content ?? ''), body.encoding || config.encoding)
-          if (!st) await mkdirRemoteDirs(sftp, remoteDirname(p))
-          await sftp.writeFile(p, buf)
-          audit('write', `write ${p}`, 0)
-          const st2 = await sftp.stat(p).catch(() => null)
-          return sendJson(res, 200, { ok: true, bytes: buf.byteLength, mtime: st2 ? st2.mtime : Math.floor(Date.now() / 1000) })
-        } catch (err) {
-          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
-        }
-      },
-    },
-    {
-      // Generic remote fs ops used by the sidebar context menu + picker:
-      // mkdir / rename / remove (recursive) / write / append.
-      kind: 'exact',
-      path: '/dsh-remote/fs',
-      handler: async (req, res) => {
-        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
-        try {
-          const body = JSON.parse((await readBody(req)) || '{}')
-          const op = String(body.op || '')
-          const sftp = await pool.sftp()
-          if (op === 'mkdir') {
-            const p = normalizeRemotePath(String(body.path || ''))
-            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
-            await mkdirRemoteDirs(sftp, p)
-            audit('mkdir', `mkdir ${p}`, 0)
-            return sendJson(res, 200, { ok: true })
-          }
-          if (op === 'rename') {
-            const p = normalizeRemotePath(String(body.path || ''))
-            const d = normalizeRemotePath(String(body.dest || ''))
-            if (!p || !d) return sendJson(res, 400, { ok: false, error: 'path and dest required' })
-            await sftp.rename(p, d)
-            audit('move', `move ${p} → ${d}`, 0)
-            return sendJson(res, 200, { ok: true })
-          }
-          if (op === 'remove') {
-            const p = normalizeRemotePath(String(body.path || ''))
-            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
-            const st = await sftp.stat(p).catch(() => null)
-            if (!st) return sendJson(res, 404, { ok: false, error: 'not found' })
-            if (st.isDirectory && st.isDirectory()) {
-              await removeRemoteTree(sftp, p)
-            } else {
-              await sftp.unlink(p)
-            }
-            audit('remove', `remove ${p}`, 0)
-            return sendJson(res, 200, { ok: true })
-          }
-          if (op === 'write' || op === 'append') {
-            const p = normalizeRemotePath(String(body.path || ''))
-            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
-            let content = ''
-            if (op === 'append') {
-              try { content = decodeBuf(await sftp.readFile(p), body.encoding || config.encoding) } catch { /* new */ }
-            }
-            const buf = encodeText(content + String(body.content ?? ''), body.encoding || config.encoding)
-            if (op === 'write' && !(await sftp.stat(p).catch(() => null))) await mkdirRemoteDirs(sftp, remoteDirname(p))
-            await sftp.writeFile(p, buf)
-            audit(op, `${op} ${p}`, 0)
-            return sendJson(res, 200, { ok: true, bytes: buf.byteLength })
-          }
-          if (op === 'download') {
-            // Download a remote file into the current workspace mirror.
-            const p = normalizeRemotePath(String(body.path || ''))
-            const ws = wsPath()
-            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
-            if (!ws) return sendJson(res, 400, { ok: false, error: 'no remote workspace set' })
-            const st = await sftp.stat(p).catch(() => null)
-            if (!st) return sendJson(res, 404, { ok: false, error: 'not found' })
-            if (config.maxFileBytes > 0 && st.size > config.maxFileBytes) {
-              return sendJson(res, 400, { ok: false, error: `file is ${st.size} bytes (over ${config.maxFileBytes} cap)` })
-            }
-            const base = mirrorDirFor(ws, config.host, config.username, config.port)
-            const rel = p.startsWith(ws) ? p.slice(ws.length).replace(/^\/+/, '') : p.slice(1)
-            const local = path.join(base, rel)
-            mkdirSync(path.dirname(local), { recursive: true })
-            await sftp.fastGet(p, local)
-            audit('download', `download ${p}`, 0)
-            return sendJson(res, 200, { ok: true, bytes: st.size, local })
-          }
-          return sendJson(res, 400, { ok: false, error: 'unknown op' })
-        } catch (err) {
-          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
-        }
-      },
-    },
+    ...createFsRoutes({
+      sendJson, readBody, resolveRequestBinding, decodeBuf, encodeText, audit, config, mirrorDirFor,
+    }),
+
     {
       kind: 'exact',
       path: '/dsh-remote/workspace',
@@ -3046,7 +2226,7 @@ export async function apply(ctx, config) {
             } : undefined,
             connectTimeoutMs: Math.min(Math.max(Number(body.connectTimeoutMs) || config.connectTimeoutMs, 2000), 30000),
             commandTimeoutMs: 10000,
-          })
+          }, { knownHostsFile })
           const started = Date.now()
           await probe.connect()
           await probe.exec('true', { timeoutMs: 10000 })
@@ -3091,7 +2271,7 @@ export async function apply(ctx, config) {
       path: '/dsh-remote/forget-key',
       handler: async (req, res) => {
         if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
-        createHostKeyGuard(config).forgetHost()
+        createHostKeyGuard(config, knownHostsFile()).forgetHost()
         return sendJson(res, 200, { ok: true, ...status() })
       },
     },