dsh-remote 0.5.10 → 0.6.9

package/lib/index.js

@@ -18,7 +18,9 @@
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import ssh2 from 'ssh2'
-import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, utimesSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 
@@ -53,6 +55,13 @@ export const Config = z.object({
   connectTimeoutMs: z.number().step(1).min(1000).default(15000),
   /** Hard ceiling on collected remote output per call. */
   maxOutputChars: z.number().step(1).min(1024).default(200000),
+  /** Skip mirroring files larger than this many bytes (0 = no cap). */
+  maxFileBytes: z.number().step(1).min(0).default(52428800),
+  /** Host-key policy: `accept-new` (default) records a host's key on first
+   * connect and verifies it afterwards (mirrors ssh's StrictHostKeyChecking
+   * accept-new); `verify` also rejects hosts never seen before; `off` skips
+   * verification entirely (MITM-unsafe, not recommended). */
+  hostKeyMode: z.string().default('accept-new'),
 })
 
 // ── shell / path helpers (proven in the read tooling) ───────────────────────
@@ -62,10 +71,46 @@ function shq(s) {
   return "'" + String(s).replace(/'/g, "'\\''") + "'"
 }
 
-/** Collapse `.`/`..`/duplicate slashes into a clean absolute remote path. */
+/**
+ * Normalize a remote path into a clean absolute path, supporting BOTH POSIX
+ * (`/home/user`) and Windows (`D:\Code`, `C:/Users/x`, `\\server\share`) forms.
+ *
+ * - POSIX paths keep `/` separators and a leading `/`.
+ * - Windows drive paths keep their `X:` prefix and are returned with `\`
+ *   separators (the native form on a Windows remote); a leading `/` is NOT
+ *   added, so `D:\Code` stays `D:\Code` instead of becoming `/D:\Code`.
+ * - UNC paths (`\\server\share\…`) keep the `\\server\share` prefix.
+ * - `.` / `..` segments are collapsed in both separator styles.
+ */
 function normalizeRemotePath(p) {
+  const s = String(p)
+  // Windows UNC: \\server\share\…
+  const unc = s.match(/^(\\\\[^\\]+(?:\\[^\\]+)?)(?:\\|$)(.*)$/s)
+  if (unc) {
+    const [prefix, rest] = [unc[1], unc[2]]
+    const parts = []
+    for (const seg of rest.split(/[\\/]+/)) {
+      if (seg === '' || seg === '.') continue
+      if (seg === '..') { parts.pop(); continue }
+      parts.push(seg)
+    }
+    return parts.length ? prefix + '\\' + parts.join('\\') : prefix
+  }
+  // Windows drive: X:\… or X:/…
+  const drive = s.match(/^([a-zA-Z]:)(?:[\\/]|$)(.*)$/s)
+  if (drive) {
+    const [prefix, rest] = [drive[1], drive[2]]
+    const parts = []
+    for (const seg of rest.split(/[\\/]+/)) {
+      if (seg === '' || seg === '.') continue
+      if (seg === '..') { parts.pop(); continue }
+      parts.push(seg)
+    }
+    return prefix + '\\' + parts.join('\\')
+  }
+  // POSIX: /a/b/c
   const parts = []
-  for (const seg of String(p).split('/')) {
+  for (const seg of s.split('/')) {
     if (seg === '' || seg === '.') continue
     if (seg === '..') {
       parts.pop()
@@ -76,12 +121,57 @@ function normalizeRemotePath(p) {
   return '/' + parts.join('/')
 }
 
-/** Parent dir of a remote absolute path (string-level). */
+/** Join a remote dir + entry name, honoring the dir's own separator style. */
+function joinRemotePath(dir, name) {
+  const d = String(dir)
+  if (!d) return String(name)
+  if (d.endsWith('/') || d.endsWith('\\')) return d + String(name)
+  return d + (d.includes('\\') ? '\\' : '/') + String(name)
+}
+
+/** Create every level of a remote dir via SFTP (mkdir -p semantics), working
+ * for both POSIX (`/a/b`) and Windows (`D:\a\b`) paths. Best effort: an
+ * existing or permission-denied level is skipped. */
+async function mkdirRemoteDirs(sftp, dir) {
+  const parent = remoteDirname(dir)
+  const isWin = parent.includes('\\')
+  // Split off a Windows drive prefix (D:) so it is not treated as a segment.
+  const drive = isWin ? (parent.match(/^([a-zA-Z]:)[\\/]?(.*)$/s) || null) : null
+  const segs = drive ? drive[2].split(/[\\/]/).filter(Boolean) : parent.split(/[\\/]/).filter(Boolean)
+  let cur = isWin ? (drive ? drive[1] + '\\' : '') : ''
+  // Drive root (D:\) itself, best effort (usually exists).
+  if (isWin && cur) { try { await sftp.mkdir(cur) } catch { /* exists */ } }
+  for (const s of segs) {
+    if (cur) {
+      if (!cur.endsWith('\\') && !cur.endsWith('/')) cur += isWin ? '\\' : '/'
+      cur += s
+    } else {
+      cur = (isWin ? s + ':' : '/' + s)
+    }
+    try { await sftp.mkdir(cur) } catch { /* exists or no perms */ }
+  }
+}
+
+/** Parent dir of a remote absolute path (string-level; POSIX or Windows). */
 function remoteDirname(p) {
   const norm = normalizeRemotePath(p)
-  if (norm === '/') return '/'
-  const idx = norm.lastIndexOf('/')
-  return idx <= 0 ? '/' : norm.slice(0, idx)
+  // Windows drive/UNC root: D:\ or \\server\share
+  if (norm === '/' || /^[a-zA-Z]:\\?$/.test(norm) || /^\\\\[^\\]+\\[^\\]+$/.test(norm)) {
+    // Ensure a drive root ends with a backslash: D: → D:\
+    const m = norm.match(/^([a-zA-Z]:)$/)
+    return m ? m[1] + '\\' : norm
+  }
+  const sep = norm.includes('\\') ? '\\' : '/'
+  const idx = norm.lastIndexOf(sep)
+  if (idx <= 0) {
+    // Windows drive with a child (D:\Code) → D:\
+    const m = norm.match(/^([a-zA-Z]:)\\/)
+    return m ? m[1] + '\\' : sep === '/' && norm.startsWith('/') ? '/' : norm
+  }
+  // A parent that is a Windows drive root also needs the trailing backslash.
+  const parent = norm.slice(0, idx)
+  if (sep === '\\' && /^[a-zA-Z]:$/.test(parent)) return parent + '\\'
+  return parent
 }
 
 function truncate(s, max) {
@@ -95,23 +185,111 @@ function truncate(s, max) {
 // workspace. dsh-remote syncs that local mirror <-> the remote over SFTP.
 
 const remotePathBase = (p) => {
-  const norm = normalizeRemotePath(p).replace(/\/+$/, '')
-  const base = norm.split('/').pop()
-  return base || 'workspace'
+  const norm = normalizeRemotePath(p).replace(/[\\/]+$/, '')
+  const base = norm.split(/[\\/]/).pop()
+  // Windows drive root (D:\) has no meaningful basename
+  if (!base || /^[a-zA-Z]:$/.test(base)) return 'workspace'
+  return base
+}
+
+/**
+ * Convert an internal remote path (POSIX `/a/b` or Windows `D:\Code`) into the
+ * path format the SFTP server understands.
+ *
+ * Windows OpenSSH's sftp-server accepts POSIX-style paths: a drive letter is
+ * written `/D:/…` (equivalent to `D:\…`). POSIX paths pass through unchanged.
+ * UNC paths are kept as-is (the server resolves `\\server\share` itself).
+ */
+function toSftpPath(p) {
+  const norm = normalizeRemotePath(p)
+  const m = norm.match(/^([a-zA-Z]):\\(.*)$/s)
+  if (m) return '/' + m[1] + ':/' + m[2].replace(/\\/g, '/')
+  return norm
+}
+
+/** Harness home: respect `DSH_HOME` when set (the desktop app sets it to its
+ * own `userData/harness`), otherwise fall back to `~/.dsh`. Keeping plugin
+ * data under the same root the harness uses means uninstalling / upgrading the
+ * app no longer leaves state behind in the home directory. */
+function dshBase() {
+  const env = process.env.DSH_HOME
+  if (env && String(env).trim()) return path.resolve(String(env).trim())
+  return path.join(homedir(), '.dsh')
+}
+
+/** Root holding every remote host's mirrors + the machine registry. */
+function remoteWorkspacesRoot() {
+  return path.join(dshBase(), 'remote-workspaces')
+}
+
+/** Recursive directory copy (EXDEV fallback for migrateLegacyData). */
+function copyDirSync(from, to) {
+  mkdirSync(to, { recursive: true })
+  for (const e of readdirSync(from, { withFileTypes: true })) {
+    const s = path.join(from, e.name)
+    const d = path.join(to, e.name)
+    if (e.isDirectory()) copyDirSync(s, d)
+    else try { copyFileSync(s, d) } catch { /* skip unreadable */ }
+  }
+}
+
+/** One-time migration of pre-0.6 data (which lived at `~/.dsh/remote-workspaces`
+ * regardless of `DSH_HOME`). Moves the legacy dir into the current home so a
+ * desktop install keeps its existing machines and mirrors. Idempotent; a
+ * rename across devices falls back to a copy. */
+function migrateLegacyData() {
+  const legacy = path.join(homedir(), '.dsh', 'remote-workspaces')
+  const target = remoteWorkspacesRoot()
+  if (legacy === target || !existsSync(legacy) || existsSync(target)) return
+  try {
+    mkdirSync(path.dirname(target), { recursive: true })
+    try {
+      renameSync(legacy, target)
+    } catch (err) {
+      if (err.code !== 'EXDEV') throw err
+      copyDirSync(legacy, target)
+    }
+  } catch {
+    // Migration is best-effort: a fresh registry is created on next save.
+  }
+}
+
+/** 32-bit string hash rendered in base36 (short, collision-safe enough). */
+function shortHash(s) {
+  let h = 0
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) - h + s.charCodeAt(i)) | 0
+  }
+  return (h >>> 0).toString(36)
 }
 
 /** Stable local root for one remote host's mirrors */
 function mirrorRootFor(host, user, port) {
   const tag = [host, user, port].filter(Boolean).join('-').replace(/[^a-zA-Z0-9._-]/g, '_')
-  return path.join(homedir(), '.dsh', 'remote-workspaces', tag)
+  return path.join(remoteWorkspacesRoot(), tag)
 }
 
 /** Local mirror dir for a specific remote path (idempotent → returns same dir).
  * Named after the remote directory's basename so the harness workspace label
- * reads cleanly (e.g. .../project) instead of a concatenated hash string. */
+ * reads cleanly (e.g. .../project). When the plain basename dir is already
+ * taken by a DIFFERENT remote path on the same host, a short path-hash suffix
+ * is appended so mirrors never collide. */
 function mirrorDirFor(remotePath, host, user, port) {
   const base = remotePathBase(remotePath)
-  return path.join(mirrorRootFor(host, user, port), base)
+  const root = mirrorRootFor(host, user, port)
+  const plain = path.join(root, base)
+  const norm = normalizeRemotePath(remotePath)
+  // A pre-existing mirror for this exact remote origin → reuse it (idempotent).
+  try {
+    const meta = JSON.parse(readFileSync(path.join(plain, '.dsh-remote-meta.json'), 'utf8'))
+    if (meta.remotePath === norm) return plain
+  } catch {
+    /* no mirror yet → fall through */
+  }
+  // Plain dir is free → first mirror for this basename keeps the clean name.
+  // It exists but points elsewhere (or is a non-mirror dir) → hashed variant.
+  if (!existsSync(plain)) return plain
+  return path.join(root, base + '-' + shortHash(norm))
 }
 
 /** Create the local mirror dir + a meta file describing its remote origin. */
@@ -120,82 +298,130 @@ function ensureMirror(remotePath, host, user, port) {
   mkdirSync(dir, { recursive: true })
   writeFileSync(
     path.join(dir, '.dsh-remote-meta.json'),
-    JSON.stringify({ host, port, username: user, remotePath, createdAt: new Date().toISOString() }, null, 2),
+    JSON.stringify({ host, port, username: user, remotePath: normalizeRemotePath(remotePath), createdAt: new Date().toISOString() }, null, 2),
   )
   return dir
 }
 
-/** Recursively sync remote → local mirror. Bounded by depth/files. */
-async function syncTree(sftp, remoteDir, localDir, maxDepth, maxFiles) {
+/** Run `fn` over `items` with at most `limit` concurrent in-flight calls. */
+async function mapLimit(items, limit, fn) {
+  const limitN = Math.max(1, Math.min(Math.floor(limit) || 1, items.length))
+  let next = 0
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++
+      try { await fn(items[i], i) } catch { /* per-item errors are the fn's concern */ }
+    }
+  }
+  const workers = []
+  for (let w = 0; w < limitN; w++) workers.push(worker())
+  await Promise.all(workers)
+}
+
+/** Recursively sync remote → local mirror. Bounded by depth/files/size;
+ * skips files whose size+mtime already match locally. Returns counters. */
+async function syncTree(sftp, remoteDir, localDir, maxDepth, maxFiles, maxFileBytes) {
   const entries = await sftp.readdir(remoteDir).then(
     (list) => list,
     () => [],
   )
-  let files = 0
-  const touched = []
+  const stats = { files: 0, dirs: 0, skippedUnchanged: 0, skippedLarge: 0, touched: [] }
+
+  // Directories first (sequential, depth-bounded) so every file has a home.
   for (const e of entries) {
     const name = String(e.filename)
     if (name === '.' || name === '..') continue
-    const rp = remoteDir === '/' ? '/' + name : remoteDir + '/' + name
-    const lp = path.join(localDir, name)
     const isDir = e.attrs && e.attrs.isDirectory && e.attrs.isDirectory()
-    if (isDir) {
-      if (maxDepth <= 0) continue
-      mkdirSync(lp, { recursive: true })
-      const sub = await syncTree(sftp, rp, lp, maxDepth - 1, maxFiles)
-      files += sub.files
-      touched.push(...sub.touched)
-      continue
-    }
-    if (files >= maxFiles) break
+    if (!isDir) continue
+    if (maxDepth <= 0 || stats.files >= maxFiles) continue
+    const rp = joinRemotePath(remoteDir, name)
+    const lp = path.join(localDir, name)
+    mkdirSync(lp, { recursive: true })
+    const sub = await syncTree(sftp, rp, lp, maxDepth - 1, maxFiles - stats.files, maxFileBytes)
+    stats.dirs += sub.dirs + 1
+    stats.files += sub.files
+    stats.skippedUnchanged += sub.skippedUnchanged
+    stats.skippedLarge += sub.skippedLarge
+    stats.touched.push(...sub.touched)
+    if (stats.files >= maxFiles) break
+  }
+  if (stats.files >= maxFiles) return stats
+
+  // Files in one bounded-parallel sweep per directory level.
+  const fileEntries = entries.filter(
+    (e) => !(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory()) &&
+      String(e.filename) !== '.' && String(e.filename) !== '..',
+  )
+  await mapLimit(fileEntries, 4, async (e) => {
+    if (stats.files >= maxFiles) return
+    const name = String(e.filename)
+    const rp = joinRemotePath(remoteDir, name)
+    const lp = path.join(localDir, name)
     try {
+      const st = await sftp.stat(rp)
+      if (maxFileBytes > 0 && st.size > maxFileBytes) { stats.skippedLarge++; return }
+      const lpStat = existsSync(lp) ? statSync(lp) : null
+      const unchanged = lpStat && lpStat.size === st.size && Math.floor(lpStat.mtimeMs / 1000) === st.mtime
+      if (unchanged) { stats.skippedUnchanged++; return }
       const buf = await sftp.readFile(rp)
       writeFileSync(lp, buf)
-      touched.push(rp)
-      files++
+      try { utimesSync(lp, new Date(st.mtime * 1000), new Date(st.mtime * 1000)) } catch {}
+      stats.files++
+      stats.touched.push(rp)
     } catch {
       /* skip unreadable */
     }
-  }
-  return { files, touched }
+  })
+  return stats
 }
 
-/** Recursively upload a local mirror tree → remote SFTP dir. Bounded by files. */
-async function pushTree(sftp, localDir, remoteDir, remoteBaseDir, maxFiles) {
+/** Recursively upload a local mirror tree → remote SFTP dir. Bounded by files;
+ * skips files whose remote copy already matches (same size, remote no older). */
+async function pushTree(sftp, localDir, remoteDir, maxFiles, maxFileBytes) {
   const entries = readdirSync(localDir, { withFileTypes: true }).filter((e) => e.name !== '.dsh-remote-meta.json')
-  let files = 0
-  let dirsCreated = 0
-  const pushed = []
+  const stats = { files: 0, dirs: 0, skippedUnchanged: 0, skippedLarge: 0, pushed: [] }
+
   for (const e of entries) {
-    if (e.isDirectory()) {
-      const rp = remoteDir === '/' ? '/' + e.name : remoteDir + '/' + e.name
-      try {
-        await sftp.mkdir(rp)
-        dirsCreated++
-      } catch { /* already exists */ }
-      const sub = await pushTree(sftp, path.join(localDir, e.name), rp, remoteBaseDir, maxFiles)
-      files += sub.files
-      pushed.push(...sub.pushed)
-      continue
-    }
-    if (files >= maxFiles) break
+    if (!e.isDirectory()) continue
+    if (stats.files >= maxFiles) break
+    const rp = joinRemotePath(remoteDir, e.name)
+    try { await sftp.mkdir(rp) } catch { /* already exists */ }
+    stats.dirs++
+    const sub = await pushTree(sftp, path.join(localDir, e.name), rp, maxFiles - stats.files, maxFileBytes)
+    stats.files += sub.files
+    stats.skippedUnchanged += sub.skippedUnchanged
+    stats.skippedLarge += sub.skippedLarge
+    stats.pushed.push(...sub.pushed)
+    if (stats.files >= maxFiles) break
+  }
+  if (stats.files >= maxFiles) return stats
+
+  const fileEntries = entries.filter((e) => !e.isDirectory())
+  await mapLimit(fileEntries, 4, async (e) => {
+    if (stats.files >= maxFiles) return
     const lp = path.join(localDir, e.name)
-    const rp = remoteDir === '/' ? '/' + e.name : remoteDir + '/' + e.name
+    const rp = joinRemotePath(remoteDir, e.name)
     try {
+      const lstat = statSync(lp)
+      if (maxFileBytes > 0 && lstat.size > maxFileBytes) { stats.skippedLarge++; return }
+      let rstat = null
+      try { rstat = await sftp.stat(rp) } catch { /* remote file absent → upload */ }
+      const unchanged = rstat && rstat.size === lstat.size && rstat.mtime >= Math.floor(lstat.mtimeMs / 1000)
+      if (unchanged) { stats.skippedUnchanged++; return }
       const buf = readFileSync(lp)
       await sftp.writeFile(rp, buf)
-      pushed.push(rp)
-      files++
+      stats.files++
+      stats.pushed.push(rp)
     } catch {
       /* skip unreadable / unwritable */
     }
-  }
-  return { files, pushed }
+  })
+  return stats
 }
 
 // ── persistent multi-machine registry ─────────────────────────────────────
 const MACHINES_FILE = 'machines.json'
-const machinesFile = () => path.join(homedir(), '.dsh', 'remote-workspaces', MACHINES_FILE)
+const machinesFile = () => path.join(remoteWorkspacesRoot(), MACHINES_FILE)
 function loadMachines() {
   try {
     const j = JSON.parse(readFileSync(machinesFile(), 'utf8'))
@@ -225,6 +451,98 @@ function applyMachine(config, m) {
 }
 function machineId() { return 'm-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 6) }
 
+// ── host-key registry (TOFU: trust-on-first-use, like ssh accept-new) ──────
+const KNOWN_HOSTS_FILE = 'known_hosts.json'
+const knownHostsFile = () => path.join(remoteWorkspacesRoot(), KNOWN_HOSTS_FILE)
+
+/** Read the trusted host-key map { "host:port": { algo, fingerprint } }. */
+function loadKnownHosts() {
+  try {
+    const j = JSON.parse(readFileSync(knownHostsFile(), 'utf8'))
+    if (j && typeof j === 'object' && !Array.isArray(j)) return j
+  } catch {}
+  return {}
+}
+
+/** Extract the host-key algorithm name from a raw SSH host-key blob
+ * (SSH wire format: `uint32 len` + algorithm string + key data). */
+function blobAlgorithm(blob) {
+  if (!Buffer.isBuffer(blob) || blob.length < 4) return ''
+  try {
+    const len = blob.readUInt32BE(0)
+    return blob.toString('utf8', 4, 4 + len)
+  } catch {
+    return ''
+  }
+}
+
+/** SHA-256 fingerprint (base64) of an ssh2 host-key blob, like `SHA256:…`
+ * in a known_hosts file (without the `SHA256:` prefix).
+ *
+ * ssh2 v1.17 passes hostVerifier the RAW host-key blob Buffer (the SSH
+ * wire-format `string(algo) string(keydata)`), NOT the old `{ algo, hash }`
+ * object. Fingerprinting `key.hash` on a raw Buffer crashed with "The 'data'
+ * argument must be of type string or an instance of Buffer, TypedArray, or
+ * DataView. Received undefined" on EVERY connect (v0.6.6 bug) — so the
+ * v0.6.1 TOFU guard never actually worked against real ssh2. Accept both
+ * shapes defensively. */
+function keyFingerprint(key) {
+  const blob = Buffer.isBuffer(key) ? key : (key && key.hash)
+  if (!blob) throw new Error('host key missing (hostVerifier received no key blob)')
+  return createHash('sha256').update(blob).digest('base64')
+}
+
+/** Build an ssh2 `hostVerifier` bound to the current config. Returns
+ * `{ mode, verifier, lastError, knownHosts, forgetHost }`. The verifier:
+ *  - `off` → always accepts;
+ *  - `accept-new` → records a host's key on first connect, rejects any CHANGE
+ *    afterwards (classic TOFU / MITM detection);
+ *  - `verify` → same, plus rejects hosts never recorded before. */
+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 OR password) ──────────────────────────────────────────────
 
 class SshPool {
@@ -232,6 +550,9 @@ class SshPool {
     this.config = config
     this.client = null
     this.connecting = 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
   }
 
   resolveKeyPath() {
@@ -257,31 +578,47 @@ class SshPool {
   connect() {
     if (this.client) return Promise.resolve(this.client)
     if (this.connecting) return this.connecting
-    this.connecting = this._doConnect().finally(() => {
-      this.connecting = null
-    })
-    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
+    }
+    // Keep the chain clean in both directions: the raw pending is what callers
+    // await (they still see rejections); this side just clears the slot.
+    pending.then(clear, clear)
+    return pending
   }
 
-  _doConnect() {
+  _doConnect(epoch) {
     return new Promise((resolve, reject) => {
       const client = new Client()
       let settled = false
+      // Fresh host-key guard per connect attempt so lastError is never stale.
+      const guard = createHostKeyGuard(this.config)
+      const isCurrent = () => this.epoch === epoch
       const fail = (err) => {
         if (settled) return
         settled = true
-        if (this.client === client) this.client = null
-        reject(err)
+        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()) {
+          // The target changed while we were connecting — never adopt this
+          // client, and make sure the caller learns the connect is void.
+          try { client.end() } catch {}
+          reject(new Error('ssh target changed during connect'))
+          return
+        }
         this.client = client
         resolve(client)
       })
       client.on('error', fail)
       client.on('close', () => {
-        if (this.client === client) this.client = null
+        if (isCurrent() && this.client === client) this.client = null
         fail(new Error('ssh connection closed'))
       })
 
@@ -292,6 +629,7 @@ class SshPool {
         readyTimeout: this.config.connectTimeoutMs,
         keepaliveInterval: 15000,
         keepaliveCountMax: 3,
+        hostVerifier: (key) => guard.verifier(key),
       }
       if (this.config.password) {
         opts.password = this.config.password
@@ -341,9 +679,17 @@ class SshPool {
               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. The hard
+              // close below frees the channel even if the process ignores it.
               try {
-                stream.close()
+                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 || this.config.commandTimeoutMs)
             stream.on('close', (code, signal) => {
@@ -369,19 +715,33 @@ class SshPool {
     )
   }
 
-  /** Resolve a promisified SFTP client for binary file transfers (sync). */
+  /** Resolve a promisified SFTP client for binary file transfers (sync).
+   * All path arguments are normalized via toSftpPath() so Windows remotes
+   * (drive-letter paths) work too. */
   sftp() {
     return this.connect().then(
       (client) =>
         new Promise((resolve, reject) => {
           client.sftp((err, sftp) => {
             if (err) return reject(new Error('ssh sftp failed: ' + ((err && err.message) || err)))
+            // Wrap a raw SFTP method so a stuck server can never hang a tool call.
+            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) => new Promise((r2, j2) => sftp.readdir(dir, (e, list) => (e ? j2(e) : r2(list)))),
-              stat: (p) => new Promise((r2, j2) => sftp.stat(p, (e, st) => (e ? j2(e) : r2(st)))),
-              mkdir: (dir) => new Promise((r2, j2) => sftp.mkdir(dir, (e) => (e ? j2(e) : r2()) )),
-              readFile: (p) => new Promise((r2, j2) => sftp.readFile(p, (e, buf) => (e ? j2(e) : r2(buf)))),
-              writeFile: (p, data) => new Promise((r2, j2) => sftp.writeFile(p, data, (e) => (e ? j2(e) : r2()))),
+              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)),
+              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),
             })
           })
         }),
@@ -389,8 +749,17 @@ class SshPool {
   }
 
   close() {
+    // Bump the epoch so any in-flight connect is orphaned, drop the pending
+    // promise (its rejection becomes nobody's problem — swallow it), and end
+    // the live client if there is one.
+    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 (client) {
       try {
         client.end()
@@ -405,6 +774,10 @@ export async function apply(ctx, config) {
   const pool = new SshPool(config)
   ctx.effect(() => () => pool.close(), 'dsh-remote.close')
 
+  // Bring any pre-0.6 data (~/.dsh/remote-workspaces) into the DSH_HOME-based
+  // location so existing machines + mirrors keep working after the move.
+  migrateLegacyData()
+
   // ── machine registry (multi-host) ─────────────────────────────────────────
   const store = loadMachines()
   const machines = store.list
@@ -433,6 +806,19 @@ export async function apply(ctx, config) {
     if (cur && cur.host) applyMachine(config, cur)
   }
 
+  /** Set the active remote workspace AND persist it on the current machine so
+   * it survives restarts (previously a tool-set workspace reset on reload). */
+  const persistWorkspace = (p) => {
+    config.workspace = p
+    if (store.currentId) {
+      const i = machineIndex(store.currentId)
+      if (i >= 0) {
+        machines[i].workspace = p
+        saveMachines(machines, store.currentId)
+      }
+    }
+  }
+
   const run = async (cmd, opts = {}) => {
     const res = await pool.exec(cmd, opts.timeoutMs)
     const parts = []
@@ -445,31 +831,68 @@ export async function apply(ctx, config) {
     return text
   }
 
-  /** Structured-listing of a remote dir: name + usable type. `dir` is decided by
-   * `[ -d ]`, which FOLLOWS symlinks — so a symlink to a directory is enterable
-   * (the picker can drill into it), while a file symlink stays a file. */
+  /** Structured-listing of a remote dir: name + usable type.
+   *
+   * Uses SFTP readdir (protocol-level), so it works on ANY remote — Linux,
+   * macOS, or Windows (cmd.exe / PowerShell) — with no dependency on a POSIX
+   * shell or `ls`. Entry types come straight from SFTP attrs; symlinks are
+   * resolved with one bounded lstat (if it fails they degrade to files). */
   const listDirStructured = async (p, timeoutMs) => {
-    const target = p || '/'
-    const cmd =
-      `cd ${shq(target)} 2>/dev/null && for f in .[!.]* *; do ` +
-      `[ -e "$f" ] || [ -L "$f" ] || continue; ` +
-      `if [ -d "$f" ]; then printf 'd\\t%s\\n' "$f"; else printf 'f\\t%s\\n' "$f"; fi; done`
-    const res = await pool.exec(cmd, timeoutMs || config.commandTimeoutMs)
-    const items = []
-    if (res.code !== 0 && res.stderr) {
-      throw new Error('ls failed: ' + (res.stderr || '').trim())
+    const target = normalizeRemotePath(p || '/')
+    let sftp
+    try {
+      sftp = await pool.sftp()
+    } catch (err) {
+      throw new Error('browse failed: ' + ((err && err.message) || err))
+    }
+    let list = []
+    try {
+      list = await sftp.readdir(target)
+    } catch (err) {
+      throw new Error('browse failed: ' + ((err && err.message) || err))
     }
-    for (const line of String(res.stdout || '').split('\n')) {
-      const idx = line.indexOf('\t')
-      if (idx < 0) continue
-      const type = line.slice(0, idx)
-      const name = line.slice(idx + 1)
+    const items = []
+    const symIdx = []
+    for (const e of list) {
+      const name = String(e.filename)
       if (name === '.' || name === '..' || !name) continue
-      items.push({ type: type === 'd' ? 'dir' : 'file', name })
+      const a = e.attrs || {}
+      if (a.isSymbolicLink && a.isSymbolicLink()) {
+        items.push({ type: 'symlink', name })
+        symIdx.push(items.length - 1)
+      } else if (a.isDirectory && a.isDirectory()) {
+        items.push({ type: 'dir', name })
+      } else {
+        items.push({ type: 'file', name })
+      }
+    }
+    // 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 }
   }
 
+  /** Verify a remote path is an existing directory, via SFTP stat (works on
+   * any remote shell: POSIX sh, cmd.exe, PowerShell). Returns false when the
+   * path is missing, is a file, or the stat errors. */
+  const isRemoteDir = async (p) => {
+    const target = normalizeRemotePath(p)
+    try {
+      const sftp = await pool.sftp()
+      const st = await sftp.stat(target)
+      return !!(st && st.isDirectory && st.isDirectory())
+    } catch {
+      return false
+    }
+  }
+
   // ── remote workspace state ────────────────────────────────────────────────
 
   const wsPath = () => (config.workspace || '').trim()
@@ -482,6 +905,8 @@ export async function apply(ctx, config) {
     localMirror: wsPath() ? mirrorDirFor(wsPath(), config.host, config.username, config.port) : '',
     currentId: store.currentId || null,
     machines: machines.map(sanitizeMachine),
+    hostKeyMode: config.hostKeyMode === 'verify' || config.hostKeyMode === 'off' ? config.hostKeyMode : 'accept-new',
+    hostKeyKnown: config.host ? isHostKeyKnown(config.host, config.port) : false,
   })
 
   // ── tools ─────────────────────────────────────────────────────────────────
@@ -495,7 +920,7 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_info',
       description:
-        'Show the remote environment: host/user/port, connection health, and the current remote workspace path. Call this first to orient, or when a remote_* call fails to check connectivity.',
+        'Show the remote environment: host/user/port, connection health, and the current remote workspace path. Call this first to orient, or when an rw_* call fails to check connectivity.',
       parameters: {},
       output: {
         schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
@@ -506,12 +931,14 @@ export async function apply(ctx, config) {
         const lines = [
           `Remote host: ${s.username || '<user>'}@${s.host || '<host>'}:${s.port}`,
           `Current remote workspace: ${s.workspace || '(none — call rw_pick_workspace to set one)'}`,
+          `Local mirror: ${s.localMirror || '(none)'}`,
           `Connected: ${s.connected ? 'yes' : 'no'}`,
           '',
         ]
         if (s.host && s.workspace) {
           try {
-            const res = await pool.exec('echo ok; hostname; pwd', Math.min(config.commandTimeoutMs, 8000))
+            // `echo ok` only — the `;`-joined probes broke on cmd.exe remotes.
+            const res = await pool.exec('echo ok', Math.min(config.commandTimeoutMs, 8000))
             if (res.signal === 'TIMEOUT') lines.push('Ping: timeout')
             else if (res.code === 0) lines.push('Ping: OK — ' + res.stdout.replace(/\s+/g, ' ').trim())
             else lines.push('Ping: FAILED — ' + (res.stderr || res.stdout || `exit ${res.code}`).trim())
@@ -551,9 +978,9 @@ export async function apply(ctx, config) {
           privateKeyPath: args.privateKeyPath || undefined,
         })
         try {
-          const res = await pool.exec('echo ok; hostname', 8000)
+          const res = await pool.exec('echo ok', 8000)
           if (res.code !== 0 && !res.stdout) return { text: 'connect failed: ' + (res.stderr || 'exit ' + res.code) }
-          return { text: `Connected to ${host} as ${config.username}.\nhostname: ${res.stdout.replace(/\s+/g, ' ').trim()}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
+          return { text: `Connected to ${host} as ${config.username}.\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
         } catch (err) {
           throw err
         }
@@ -574,13 +1001,12 @@ export async function apply(ctx, config) {
       async execute(args) {
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_pick_workspace: path must be an absolute directory')
-        const res = await pool.exec(`if [ -d ${shq(p)} ]; then echo DIR; else echo NOTDIR; fi`)
-        const ok = res.stdout.trim() === 'DIR'
+        const ok = await isRemoteDir(p)
         if (!ok) return { text: `not a directory (or missing) on ${p}` }
-        config.workspace = p
+        persistWorkspace(p)
         const local = ensureMirror(p, config.host, config.username, config.port)
         return {
-          text: `Remote workspace set to ${p} on ${config.username}@${config.host}.\nLocal mirror (native workspace path): ${local}\n\nRun rw_sync to download its files into the local mirror.`,
+          text: `Remote workspace set to ${p} on ${config.username}@${config.host} (saved for this machine).\nLocal mirror (native workspace path): ${local}\n\nRun rw_sync to download its files into the local mirror.`,
         }
       },
     }),
@@ -610,8 +1036,11 @@ export async function apply(ctx, config) {
         } catch (err) {
           return { text: 'sftp unavailable: ' + ((err && err.message) || err) }
         }
-        const { files, touched } = await syncTree(sftp, p, local, depth, maxFiles)
-        return { text: `Downloaded ${files} file(s) from ${p} → ${local}${files >= maxFiles ? ' (hit download cap)' : ''}.` }
+        const r = await syncTree(sftp, p, local, depth, maxFiles, config.maxFileBytes)
+        let text = `Downloaded ${r.files} file(s) from ${p} → ${local}${r.files >= maxFiles ? ' (hit download cap)' : ''}.`
+        if (r.skippedUnchanged) text += ` ${r.skippedUnchanged} unchanged.`
+        if (r.skippedLarge) text += ` ${r.skippedLarge} too large (over ${config.maxFileBytes} bytes).`
+        return { text }
       },
     }),
 
@@ -638,8 +1067,11 @@ export async function apply(ctx, config) {
         } catch (err) {
           return { text: 'sftp unavailable: ' + ((err && err.message) || err) }
         }
-        const { files } = await pushTree(sftp, local, p, p, maxFiles)
-        return { text: `Uploaded ${files} file(s) from ${local} → ${p}.` }
+        const { files, skippedUnchanged, skippedLarge, pushed } = await pushTree(sftp, local, p, maxFiles, config.maxFileBytes)
+        let text = `Uploaded ${files} file(s) from ${local} → ${p}.`
+        if (skippedUnchanged) text += ` ${skippedUnchanged} unchanged.`
+        if (skippedLarge) text += ` ${skippedLarge} too large (over ${config.maxFileBytes} bytes).`
+        return { text }
       },
     }),
 
@@ -657,7 +1089,24 @@ export async function apply(ctx, config) {
       async execute(args) {
         const p = args.path ? normalizeRemotePath(String(args.path)) : wsPath()
         if (!p) throw new Error('rw_list_dir: no path and no remote workspace set')
-        return { text: await run(`ls -la --color=never ${shq(p)}`) }
+        // SFTP readdir listing — works on any remote shell (POSIX, cmd.exe,
+        // PowerShell) unlike `ls -la`.
+        let list
+        try {
+          const sftp = await pool.sftp()
+          list = await sftp.readdir(p)
+        } catch (err) {
+          throw new Error('rw_list_dir: ' + ((err && err.message) || err))
+        }
+        const lines = list
+          .filter((e) => String(e.filename) !== '.' && String(e.filename) !== '..')
+          .map((e) => {
+            const a = e.attrs || {}
+            const type = a.isDirectory && a.isDirectory() ? 'd' : (a.isSymbolicLink && a.isSymbolicLink() ? 'l' : '-')
+            const size = typeof a.size === 'number' ? String(a.size) : '?'
+            return `${type} ${size.padStart(10)} ${String(e.filename)}`
+          })
+        return { text: lines.length ? lines.join('\n') : '(empty directory)' }
       },
     }),
 
@@ -682,8 +1131,19 @@ export async function apply(ctx, config) {
         let from = Math.max(Number(args.startLine) || 1, 1)
         let to = Number(args.endLine) || 0
         if (!to || to - from + 1 > maxLines) to = from + maxLines - 1
-        const raw = await run(`sed -n '${from},${to}p' -- ${shq(p)}`, { timeoutMs: config.commandTimeoutMs })
-        const numbered = raw.split('\n').map((l, i) => `${String(from + i).padStart(6)}\t${l}`).join('\n').replace(/\s+$/, '')
+        // SFTP readFile is used instead of `sed -n` so Windows remotes (cmd.exe
+        // / PowerShell, no POSIX sed) work too.
+        let buf
+        try {
+          const sftp = await pool.sftp()
+          buf = await sftp.readFile(p)
+        } catch (err) {
+          throw new Error('rw_read_file: ' + ((err && err.message) || err))
+        }
+        const content = buf.toString('utf8').replace(/\r\n/g, '\n')
+        const allLines = content.split('\n')
+        const page = allLines.slice(from - 1, to)
+        const numbered = page.map((l, i) => `${String(from + i).padStart(6)}\t${l}`).join('\n').replace(/\s+$/, '')
         let text = numbered === '' ? '(empty or out of range)' : numbered
         if (!args.endLine) text += '\n(shown up to ' + maxLines + ' lines; use startLine/endLine to page)'
         return { text }
@@ -693,9 +1153,10 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_exec',
       description:
-        'Run a shell command on the remote host. Use for anything that is not reading a file (build, test, grep, etc). Output is capped.',
+        'Run a shell command on the remote host. Use for anything that is not reading a file (build, test, grep, etc). Output is capped. Runs in the current remote workspace by default; pass cwd to run elsewhere.',
       parameters: {
         command: { type: 'string', required: true, description: 'Shell command (run on the remote host)' },
+        cwd: { type: 'string', description: 'Working directory for the command (default: the current remote workspace)' },
       },
       output: {
         schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
@@ -704,7 +1165,12 @@ export async function apply(ctx, config) {
       async execute(args) {
         const cmd = String(args.command || '')
         if (!cmd) throw new Error('rw_exec: command is required')
-        return { text: await run(cmd, { timeoutMs: config.commandTimeoutMs }) }
+        const ws = wsPath()
+        const cwd = args.cwd ? normalizeRemotePath(String(args.cwd)) : (ws || '')
+        // Windows remotes: no POSIX cd/single-quotes — let the command run as-is
+        // (the user writes cmd/PowerShell). POSIX remotes get `cd … && cmd`.
+        const full = cwd && !cwd.includes('\\') ? `cd ${shq(cwd)} && ${cmd}` : cmd
+        return { text: await run(full, { timeoutMs: config.commandTimeoutMs }) }
       },
     }),
 
@@ -733,15 +1199,9 @@ export async function apply(ctx, config) {
         }
         const mkdir = args.mkdir !== false
         if (mkdir) {
-          const parent = remoteDirname(p)
           // create each level from the root so mkdir -p semantics survive even
           // when intermediate privileged-parent dirs don't allow create (best effort)
-          const segs = parent.split('/').filter(Boolean)
-          let cur = ''
-          for (const s of segs) {
-            cur += '/' + s
-            try { await sftp.mkdir(cur) } catch { /* exists or no perms */ }
-          }
+          await mkdirRemoteDirs(sftp, p)
         }
         const buf = Buffer.from(content, 'utf8')
         await sftp.writeFile(p, buf)
@@ -750,6 +1210,110 @@ export async function apply(ctx, config) {
       },
     }),
 
+    defineTool({
+      name: 'rw_search',
+      description:
+        'Search remote files for a pattern (grep, recursive, case-insensitive by default). Returns matching file:line rows; output is capped. Use instead of rw_exec grep when you want a bounded, portable search.',
+      parameters: {
+        pattern: { type: 'string', required: true, description: 'Pattern to search for (extended regex)' },
+        path: { type: 'string', description: 'Directory to search (default: current remote workspace)' },
+        glob: { type: 'string', description: 'Only files whose name matches this glob, e.g. *.ts (optional)' },
+        ignoreCase: { type: 'boolean', description: 'Case-insensitive search (default true)' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
+        render: (_a, a) => [{ type: 'text', text: a.text }],
+      },
+      async execute(args) {
+        const pattern = String(args.pattern || '')
+        if (!pattern) throw new Error('rw_search: pattern is required')
+        const ws = wsPath()
+        const dir = args.path ? normalizeRemotePath(String(args.path)) : (ws || '')
+        if (!dir) throw new Error('rw_search: no path and no remote workspace set')
+        if (dir.includes('\\')) {
+          // Windows remotes have no POSIX find/grep; the search would need a
+          // recursive SFTP walk. Give an actionable hint instead of a broken cmd.
+          return { text: `rw_search does not support Windows-remote paths yet (${dir}). Use rw_exec with a PowerShell one-liner, e.g.: powershell -NoProfile -Command "Get-ChildItem -Recurse -File | Select-String -Pattern '${pattern}'"` }
+        }
+        const flags = 'r' + (args.ignoreCase === false ? '' : 'i') + 'nE'
+        const name = args.glob ? ` -name ${shq(String(args.glob))}` : ''
+        // find … -exec grep {} + is POSIX (BSD + GNU): `grep -RInE` alone would
+        // differ on BSD, and GNU-only --include is avoided in favor of find -name.
+        const cmd = `find ${shq(dir)} -type f${name} -exec grep -${flags} -H -- ${shq(pattern)} {} + 2>/dev/null | head -n 2000`
+        return { text: await run(cmd, { timeoutMs: Math.max(config.commandTimeoutMs, 30000) }) }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_download',
+      description:
+        'Download a single remote file over SFTP into the local mirror of the current workspace (or to an explicit local path). Use when you need the actual file content locally, not just its text.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote file path' },
+        localPath: { type: 'string', description: 'Local destination (default: the workspace mirror, preserving the relative path)' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: false, properties: { ok: { type: 'boolean', required: true }, bytes: { type: 'integer' }, text: { type: 'string' } } },
+        render: (_a, a) => [{ type: 'text', text: a.text || (a.ok ? 'downloaded' : 'failed') }],
+      },
+      async execute(args) {
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p || p === '/') throw new Error('rw_download: a remote file path is required')
+        let sftp
+        try {
+          sftp = await pool.sftp()
+        } catch (err) {
+          throw new Error('rw_download: sftp unavailable: ' + ((err && err.message) || err))
+        }
+        let local
+        if (args.localPath) {
+          local = path.resolve(String(args.localPath))
+        } else {
+          const ws = wsPath()
+          if (!ws) throw new Error('rw_download: no remote workspace set — pass localPath explicitly')
+          const base = mirrorDirFor(ws, config.host, config.username, config.port)
+          const rel = p.startsWith(ws) ? p.slice(ws.length).replace(/^\/+/, '') : p.slice(1)
+          local = path.join(base, rel)
+        }
+        mkdirSync(path.dirname(local), { recursive: true })
+        const buf = await sftp.readFile(p)
+        writeFileSync(local, buf)
+        const bytes = buf.byteLength
+        return { ok: true, bytes, text: `downloaded ${bytes} bytes from ${p} → ${local}` }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_upload',
+      description:
+        'Upload a local file over SFTP to a path on the remote host (creating parent directories if needed). Use to push a local file directly, without a full rw_push of the whole mirror.',
+      parameters: {
+        localPath: { type: 'string', required: true, description: 'Absolute local file path' },
+        path: { type: 'string', required: true, description: 'Absolute remote destination path' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: false, properties: { ok: { type: 'boolean', required: true }, bytes: { type: 'integer' }, text: { type: 'string' } } },
+        render: (_a, a) => [{ type: 'text', text: a.text || (a.ok ? 'uploaded' : 'failed') }],
+      },
+      async execute(args) {
+        const rp = normalizeRemotePath(String(args.path || ''))
+        const lp = String(args.localPath || '')
+        if (!rp || rp === '/' || !lp) throw new Error('rw_upload: both localPath and a remote path are required')
+        if (!existsSync(lp)) throw new Error(`rw_upload: local file not found: ${lp}`)
+        let sftp
+        try {
+          sftp = await pool.sftp()
+        } catch (err) {
+          throw new Error('rw_upload: sftp unavailable: ' + ((err && err.message) || err))
+        }
+        await mkdirRemoteDirs(sftp, rp)
+        const buf = readFileSync(lp)
+        await sftp.writeFile(rp, buf)
+        const bytes = buf.byteLength
+        return { ok: true, bytes, text: `uploaded ${bytes} bytes from ${lp} → ${rp}` }
+      },
+    }),
+
     defineTool({
       name: 'rw_disconnect',
       description:
@@ -780,7 +1344,7 @@ export async function apply(ctx, config) {
       return (
         '## Remote workspace\n' +
         `Current remote workspace: ${config.username}@${config.host}:${w}\n` +
-        'Use the remote_* tools (rw_list_dir / rw_read_file / rw_exec) to inspect and act on files on the remote host. Treat this directory as the working root for this task.'
+        'Use the rw_* tools (rw_list_dir / rw_read_file / rw_write_file / rw_exec / rw_search) to inspect and act on files on the remote host. Treat this directory as the working root for this task.'
       )
     },
   })
@@ -798,11 +1362,21 @@ export async function apply(ctx, config) {
           text:
             `Remote host: ${s.username}@${s.host || '<none>'} (connected: ${s.connected})\n` +
             `Remote workspace: ${s.workspace || '(none)'}\n` +
-            `\nUse tools: rw_list_dir / rw_read_file / rw_exec.` +
+            `Host key: ${s.hostKeyKnown ? 'trusted ✓' : 'not yet trusted'} (mode=${s.hostKeyMode})\n` +
+            (s.hostKeyKnown ? `  — if the key changed / was mistrusted, run /remote-forget-key\n` : '') +
+            `\nUse tools: rw_list_dir / rw_read_file / rw_exec / rw_search.` +
             (s.workspace ? `\nCurrently working in ${s.workspace}.` : ''),
         }
       },
     })
+    commands.register({
+      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()
+        return { kind: 'success', text: `forgot host key for ${config.host || '<none>'}:${config.port} — the next connect will re-record it.` }
+      },
+    })
   }
 
   // ── JSON endpoints for settings UI ─────────────────────────────────────────
@@ -814,13 +1388,63 @@ export async function apply(ctx, config) {
     res.setHeader('Content-Type', 'application/json; charset=utf-8')
     res.end(JSON.stringify(body))
   }
+  // Cap request bodies (1 MiB) so a malformed client cannot force us to buffer
+  // unbounded memory on a local-only route.
+  const MAX_BODY_BYTES = 1024 * 1024
   const readBody = (req) =>
     new Promise((resolve) => {
       const chunks = []
-      req.on('data', (c) => chunks.push(c))
+      let total = 0
+      req.on('data', (c) => {
+        total += c.length
+        if (total > MAX_BODY_BYTES) {
+          req.removeAllListeners('data')
+          resolve('{}')
+          return
+        }
+        chunks.push(c)
+      })
       req.on('end', () => resolve(chunks.join('')))
     })
 
+  // ── 本机目录选择器：DSH directoryPicker 服务优先，缺位/非原生则自持兜底 ──
+  // 背景：web-app 的 `directory-picker` 行（-auto）在桌面启动路径里不物化成
+  // loader 条目，`ctx.get('directoryPicker')` 实测为 null（沙箱 + 产品同路径）。
+  // 因此插件自带原生选择器：macOS osascript / Linux zenity→kdialog，与 DSH
+  // native 后端同一套调用约定（取消 → { cancelled }，成功 → { path }）。
+  const PICK_TIMEOUT_MS = 120000
+  const runPick = (bin, args) =>
+    new Promise((resolve, reject) => {
+      execFile(bin, args, { timeout: PICK_TIMEOUT_MS, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        if (err) {
+          const code = err.code
+          const msg = String(stderr || '')
+          // 用户在对话框里点了取消：osascript 退出码 1 + "User canceled"/-128
+          if (code === 1 && /(?:user canceled|-128)/i.test(msg)) return resolve({ cancelled: true })
+          if (err.signal || err.killed) return reject(new Error('目录选择已超时，请重试或直接在输入框填本地路径'))
+          if (code === 'ENOENT') return reject(Object.assign(new Error('未找到目录选择器程序 ' + bin), { code }))
+          return reject(new Error((msg.trim() || (err && err.message) || '无法打开系统文件夹选择器').split('\n')[0]))
+        }
+        const p = String(stdout || '').replace(/[\r\n]+$/, '').trim()
+        resolve(p ? { path: p } : { cancelled: true })
+      })
+    })
+  const pickLocalNative = async () => {
+    const platform = process.platform
+    if (platform === 'darwin') {
+      return runPick('osascript', ['-e', 'set selectedFolder to choose folder with prompt "Select Workspace Directory"', '-e', 'POSIX path of selectedFolder'])
+    }
+    if (platform === 'linux') {
+      try {
+        return await runPick('zenity', ['--file-selection', '--directory', '--title=Select Workspace Directory'])
+      } catch (err) {
+        if (err && err.code === 'ENOENT') return runPick('kdialog', ['--getexistingdirectory', '.', '--title', 'Select Workspace Directory'])
+        throw err
+      }
+    }
+    throw new Error('当前系统不支持自动打开目录选择器，请在输入框直接填本地路径')
+  }
+
   const routes = [
     {
       kind: 'exact',
@@ -857,8 +1481,10 @@ export async function apply(ctx, config) {
       path: '/dsh-remote/ls',
       handler: async (req, res) => {
         try {
-          const m = (req.url || '').match(/path=([^&]*)/)
-          const p = m ? decodeURIComponent(m[1]) : wsPath()
+          // Proper URL parsing so `+` in a path decodes to a literal space
+          // (the old regex missed it).
+          const q = new URL(req.url, 'http://localhost').searchParams
+          const p = q.get('path') ? decodeURIComponent(q.get('path')) : wsPath()
           const out = await listDirStructured(p || '/')
           return sendJson(res, 200, { path: p, items: out.items })
         } catch (err) {
@@ -875,9 +1501,9 @@ export async function apply(ctx, config) {
           const payload = JSON.parse((await readBody(req)) || '{}')
           const p = normalizeRemotePath(String(payload.path || ''))
           if (!p || p === '/') return sendJson(res, 400, { error: 'path must be an absolute directory' })
-          const r = await pool.exec(`if [ -d ${shq(p)} ]; then echo DIR; else echo NOTDIR; fi`)
-          if (r.stdout.trim() !== 'DIR') return sendJson(res, 400, { ok: false, error: `not a directory: ${p}` })
-          config.workspace = p
+          const okDir = await isRemoteDir(p)
+          if (!okDir) return sendJson(res, 400, { ok: false, error: `not a directory: ${p}` })
+          persistWorkspace(p)
           const local = ensureMirror(p, config.host, config.username, config.port)
           return sendJson(res, 200, { ok: true, workspace: p, localMirror: local, ...status() })
         } catch (err) {
@@ -895,13 +1521,12 @@ export async function apply(ctx, config) {
           const p = normalizeRemotePath(String(payload.path || ''))
           if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path must be an absolute directory' })
           if (!config.host) return sendJson(res, 400, { ok: false, error: 'no remote host configured/connected — connect first' })
-          // optional: verify it's a directory over SSH when connected
-          if (pool.client) {
-            const r = await pool.exec(`if [ -d ${shq(p)} ]; then echo DIR; else echo NOTDIR; fi`)
-            if (r.stdout.trim() !== 'DIR') return sendJson(res, 400, { ok: false, error: `not a directory (or unreachable): ${p}` })
-          }
+          // Always verify over SSH (connecting if needed) so an unconnected or
+          // wrong host can never silently mint a mirror for a bogus path.
+          const okDir = await isRemoteDir(p)
+          if (!okDir) return sendJson(res, 400, { ok: false, error: `not a directory (or unreachable): ${p}` })
           const local = ensureMirror(p, config.host, config.username, config.port)
-          config.workspace = p
+          persistWorkspace(p)
           return sendJson(res, 200, { ok: true, path: p, localMirror: local, ...status() })
         } catch (err) {
           return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
@@ -914,16 +1539,38 @@ export async function apply(ctx, config) {
       handler: async (req, res) => {
         if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
         try {
-          const dp = (ctx && ctx.get && ctx.get('directoryPicker')) || (ctx && ctx.directoryPicker) || null
-          if (!dp || typeof dp.capability !== 'function') return sendJson(res, 400, { ok: false, error: '本地目录选择器服务不可用（缺少 DSH directory-picker backend）' })
-          const cap = await Promise.resolve(dp.capability())
-          if (!cap || cap.kind !== 'native' || typeof cap.pick !== 'function') return sendJson(res, 400, { ok: false, error: '本地目录选择器不可用（当前为非原生/浏览后端，请在输入框手动填本地路径）' })
-          const pickAbort = new AbortController()
-          const signal = pickAbort.signal || null
-          const picked = await Promise.resolve(cap.pick(signal))
-          pickAbort.abort()
-          if (!picked || typeof picked !== 'string') return sendJson(res, 200, { ok: true, cancelled: true })
-          return sendJson(res, 200, { ok: true, path: picked })
+          // 1) 优先用 DSH directoryPicker 服务（native 后端）。必须用
+          //    ctx.get() 按名取：属性形式 ctx.directoryPicker 会抛 cordis
+          //    "cannot get property ... without inject"（该名字未在本插件
+          //    inject 里声明），ctx.get() 无此要求、缺失返回 null。
+          // 2) 服务缺位或非 native（实测 web-app 的 -auto 行在桌面启动路径
+          //    不物化后端）→ 自持 osascript/zenity/kdialog 兜底。
+          let outcome = null
+          let via = 'service'
+          const dp = (ctx && typeof ctx.get === 'function') ? (ctx.get('directoryPicker') || null) : null
+          if (dp && typeof dp.capability === 'function') {
+            try {
+              const cap = await Promise.resolve(dp.capability())
+              if (cap && cap.kind === 'native' && typeof cap.pick === 'function') {
+                const pickAbort = new AbortController()
+                const p = await Promise.resolve(cap.pick(pickAbort.signal || null))
+                pickAbort.abort()
+                outcome = (typeof p === 'string' && p) ? { path: p } : { cancelled: true }
+              }
+            } catch (err) {
+              outcome = null // DSH 服务出错 → 落到自持兜底
+            }
+          }
+          if (!outcome) {
+            via = 'own'
+            try {
+              outcome = await pickLocalNative()
+            } catch (err) {
+              return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) + ' — 可直接在输入框填本地路径' })
+            }
+          }
+          if (outcome.cancelled) return sendJson(res, 200, { ok: true, cancelled: true, via })
+          return sendJson(res, 200, { ok: true, path: outcome.path, via })
         } catch (err) {
           return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
         }
@@ -1020,6 +1667,18 @@ export async function apply(ctx, config) {
         }
       },
     },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/forget-key',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        // Drop the trusted host-key record for the CURRENT target so the next
+        // connect re-records it (use after an intentional host reinstall or a
+        // false MITM alarm).
+        createHostKeyGuard(config).forgetHost()
+        return sendJson(res, 200, { ok: true, ...status() })
+      },
+    },
   ]
 
   const disposers = routes.map((r) => webServer.register(r))