dsh-remote 0.5.9 → 0.6.7

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) ───────────────────────
@@ -100,18 +109,89 @@ const remotePathBase = (p) => {
   return base || 'workspace'
 }
 
+/** 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 +200,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 isDir = e.attrs && e.attrs.isDirectory && e.attrs.isDirectory()
+    if (!isDir) continue
+    if (maxDepth <= 0 || stats.files >= maxFiles) continue
+    const rp = remoteDir === '/' ? '/' + name : 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 = 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
     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 = remoteDir === '/' ? '/' + e.name : 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
     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 +353,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 +452,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 +480,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 +531,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 +581,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) => {
@@ -389,8 +637,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 +662,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 +694,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,27 +719,51 @@ 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.
+   *
+   * Implementation note — this deliberately uses `ls -1A -F` instead of a
+   * `for f in .[!.]* *` loop or `find`:
+   *   • `-F` marks real directories with a trailing `/` and symlinks with `@`;
+   *     on Linux GNU ls classifies from readdir `d_type` WITHOUT stat, so the
+   *     listing can never hang on a stuck FUSE/network mount the way
+   *     `[ -d "$f" ]` / `find -type` do (those stat every entry and block in
+   *     an uninterruptible D-state that even SIGTERM can't clear).
+   *   • there is no shell glob, so zsh's `nomatch` can't abort the listing on
+   *     directories that have no dotfiles (the old `.[!.]*` glob did).
+   * Symlinked entries (e.g. `/bin@`) get ONE bounded follow-up stat — only
+   * symlinks are touched, never the stuck mount — to decide dir vs file. */
   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 = []
+    const to = timeoutMs || config.commandTimeoutMs
+    const res = await pool.exec(`ls -1A -F ${shq(target)}`, to)
     if (res.code !== 0 && res.stderr) {
       throw new Error('ls failed: ' + (res.stderr || '').trim())
     }
+    const items = []
+    const symIdx = []
     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)
-      if (name === '.' || name === '..' || !name) continue
-      items.push({ type: type === 'd' ? 'dir' : 'file', name })
+      if (!line) continue
+      const c = line[line.length - 1]
+      if (c === '/') items.push({ type: 'dir', name: line.slice(0, -1) })
+      else if (c === '@') {
+        items.push({ type: 'symlink', name: line.slice(0, -1) })
+        symIdx.push(items.length - 1)
+      } else {
+        // regular file, executable (`*`), socket (`=`), fifo (`|`) …
+        items.push({ type: 'file', name: c === '*' || c === '=' || c === '|' ? line.slice(0, -1) : line })
+      }
+    }
+    // Resolve symlink-to-dir vs symlink-to-file. Bounded and failure-tolerant:
+    // if the stat is slow it times out and symlinks just degrade to files
+    // (non-enterable) instead of failing the whole browse.
+    if (symIdx.length) {
+      const cmd = 'for f in ' + symIdx.map((i) => shq(items[i].name)).join(' ') +
+        '; do if [ -d "$f" ]; then echo d; else echo f; fi; done'
+      const r2 = await pool.exec(cmd, Math.min(to, 5000))
+      const kinds = String(r2.stdout || '').split('\n')
+      for (let i = 0; i < symIdx.length; i++) {
+        items[symIdx[i]].type = (kinds[i] || '').trim() === 'd' ? 'dir' : 'file'
+      }
     }
     return { path: target, items }
   }
@@ -482,6 +780,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 +795,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,6 +806,7 @@ 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'}`,
           '',
         ]
@@ -577,10 +878,10 @@ export async function apply(ctx, config) {
         const res = await pool.exec(`if [ -d ${shq(p)} ]; then echo DIR; else echo NOTDIR; fi`)
         const ok = res.stdout.trim() === 'DIR'
         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 +911,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 +942,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 +964,9 @@ 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)}`) }
+        // `ls -la` (no --color / -N): piped output never carries color on either
+        // GNU or BSD ls, so the GNU-only flags would break macOS/BSD remotes.
+        return { text: await run(`ls -la ${shq(p)}`) }
       },
     }),
 
@@ -682,7 +991,9 @@ 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 })
+        // Absolute paths start with '/', so the GNU-only `--` terminator is
+        // dropped to keep BSD/macOS sed (which rejects `--`) working.
+        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+$/, '')
         let text = numbered === '' ? '(empty or out of range)' : numbered
         if (!args.endLine) text += '\n(shown up to ' + maxLines + ' lines; use startLine/endLine to page)'
@@ -693,9 +1004,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 +1016,10 @@ 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 || '')
+        const full = cwd ? `cd ${shq(cwd)} && ${cmd}` : cmd
+        return { text: await run(full, { timeoutMs: config.commandTimeoutMs }) }
       },
     }),
 
@@ -750,6 +1065,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')
+        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))
+        }
+        const segs = remoteDirname(rp).split('/').filter(Boolean)
+        let cur = ''
+        for (const s of segs) {
+          cur += '/' + s
+          try { await sftp.mkdir(cur) } catch { /* exists or no perms */ }
+        }
+        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 +1199,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 +1217,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 +1243,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 +1336,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) {
@@ -877,7 +1358,7 @@ export async function apply(ctx, config) {
           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
+          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 +1376,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 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}` })
           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 +1394,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 +1522,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))