dsh-remote 0.7.4 → 0.8.1

package/lib/index.js

@@ -1,28 +1,46 @@
 // dsh-remote — remote-work assistant for DeepSeek Harness.
 //
 // Host half. Turns "give me a remote host + login" into a usable REMOTE WORKSPACE:
-//   • one persistent SSH/SFTP pool per configured remote (password OR private key),
+//   • one persistent SSH/SFTP pool per configured remote (password OR private key,
+//     SSH agent, keyboard-interactive, proxy jump),
 //   • a "current remote workspace" — a remote directory the agent treats as the
 //     active project root (user@host:/path) — injected into every system prompt,
-//   • model tools `rw_info` / `rw_connect` / `rw_pick_workspace` /
-//     `rw_list_dir` / `rw_read_file` / `rw_exec`,
-//   • JSON endpoints the client settings page uses to connect → browse → select the
-//     remote workspace over the harness `webServer`.
+//   • model tools `rw_*` (info/connect/workspace/list/read/write/edit/append/mkdir/
+//     remove/move/stat/exec/search/download/upload/sync/push/forward/disconnect),
+//   • JSON endpoints the client settings page + sidebar use over the harness
+//     `webServer` (machines / ls / read / write / fs / forwards / task / audit /
+//     ssh-config / local-pick / …),
+//   • local mirror of the remote workspace (three-way conflict-aware SFTP sync),
+//   • optional OS-keychain password storage, command audit log, TOFU host keys.
 //
-// The engine (path guard + shell quoting + ssh pool + exec) reuses the foundation
-// proven by dsh-remote-debug, extended with password auth and a mutable workspace:
-// `ctx.fs` / the local workspace registry stay untouched — this is a REMOTE workspace
-// presented as such to the model and UI, not a replacement of the local one.
+// The engine (path guard + shell quoting + ssh pool + exec) keeps the proven
+// foundation; `ctx.fs` / the local workspace registry stay untouched — this is a
+// REMOTE workspace presented as such to the model and UI.
 //
 // Plugin Config MUST be a schemastery schema (zod rejects the undefined row config).
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import ssh2 from 'ssh2'
-import { createHash } from 'node:crypto'
 import { execFile } from 'node:child_process'
-import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, utimesSync } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, utimesSync, appendFileSync, unlinkSync, watch } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
+import iconv from 'iconv-lite'
+
+import {
+  shq, normalizeRemotePath, joinRemotePath, remoteDirname, mkdirRemoteDirs,
+  toSftpPath, remotePathBase, truncate, shortHash, relPathUnder,
+} from './paths.js'
+import { blobAlgorithm, keyFingerprint } from './hostkey.js'
+import { compileIgnore, DEFAULT_IGNORE } from './ignore.js'
+import { friendlyMessage } from './errors.js'
+import { importableEntries, sshConfigPath, readSshConfigText } from './sshconfig.js'
+import { saveSecret, getSecret, deleteSecret, platformBackend } from './credential.js'
+import { syncTree, pushTree, loadSyncState, saveSyncState, pushOneFile } from './sync.js'
+import { searchTree } from './search.js'
+import { TaskManager } from './tasks.js'
+import { ForwardManager } from './forwards.js'
+import { selfDir, readVersion, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode } from './update.js'
 
 const { Client } = ssh2
 
@@ -30,8 +48,7 @@ export const name = 'dsh-remote'
 
 // tools + systemPrompt + webServer are required. webServer is INJECTED (not just
 // lazily read) so this plugin activates only after the web server is up — otherwise
-// apply() runs ahead of webServer and the /dsh-remote/* JSON routes never register
-// (silently: the boot shows no error, but status/ls/workspace return the SPA fallback).
+// apply() runs ahead of webServer and the /dsh-remote/* JSON routes never register.
 export const inject = ['tools', 'systemPrompt', 'webServer']
 
 export const Config = z.object({
@@ -62,155 +79,38 @@ export const Config = z.object({
    * accept-new); `verify` also rejects hosts never seen before; `off` skips
    * verification entirely (MITM-unsafe, not recommended). */
   hostKeyMode: z.string().default('accept-new'),
+  /** Use the OpenSSH agent (SSH_AUTH_SOCK) when no password/key is configured. */
+  useAgent: z.boolean().default(false),
+  /** Allow keyboard-interactive auth (OTP/MFA chains) using the configured password. */
+  keyboardInteractive: z.boolean().default(false),
+  /** Jump host / bastion: connect through this machine first. All fields have
+   * defaults so this works on schemastery versions without `.optional()`; an
+   * empty `host` means "no jump host". */
+  proxy: z.object({
+    host: z.string().default(''),
+    port: z.number().step(1).min(1).max(65535).default(22),
+    username: z.string().default(''),
+    password: z.string().default(''),
+    privateKeyPath: z.string().default(''),
+  }),
+  /** Auto-push edited mirror files back to the remote (watcher, debounced). Default off. */
+  autoPush: z.boolean().default(false),
+  /** Append executed commands to the audit log under the harness home. */
+  auditLog: z.boolean().default(true),
+  /** Text encoding for remote file reads/writes (utf-8 default; gbk etc.). */
+  encoding: z.string().default('utf-8'),
+  /** Update mode: `manual` (default) only checks when asked; `auto` checks on
+   * load and periodically, applying a newer npm release automatically;
+   * `off` disables version checks entirely. */
+  updateMode: z.enum(['manual', 'auto', 'off']).default('manual'),
+  /** How often (ms) auto mode checks the npm registry for a newer release. */
+  updateCheckIntervalMs: z.number().step(1).min(60000).default(6 * 3600 * 1000),
 })
 
-// ── shell / path helpers (proven in the read tooling) ───────────────────────
-
-/** Single-quote one shell argument verbatim. */
-function shq(s) {
-  return "'" + String(s).replace(/'/g, "'\\''") + "'"
-}
-
-/**
- * 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 s.split('/')) {
-    if (seg === '' || seg === '.') continue
-    if (seg === '..') {
-      parts.pop()
-      continue
-    }
-    parts.push(seg)
-  }
-  return '/' + parts.join('/')
-}
-
-/** 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)
-  // 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) {
-  if (s.length <= max) return s
-  return s.slice(0, max) + `\n…[truncated: ${s.length - max} more chars]`
-}
-
-// ── local mirror of an OS remote workspace ────────────────────────────────
-// Makes a chosen remote workspace a REAL local directory (fs.realpath passes),
-// so the DSH host `workspaceRegistry.create(dir)` accepts it as a native
-// workspace. dsh-remote syncs that local mirror <-> the remote over SFTP.
-
-const remotePathBase = (p) => {
-  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
-}
+// ── shell / path helpers (pure implementations in lib/paths.js) ───────────
 
 /** 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. */
+ * own `userData/harness`), otherwise fall back to `~/.dsh`. */
 function dshBase() {
   const env = process.env.DSH_HOME
   if (env && String(env).trim()) return path.resolve(String(env).trim())
@@ -222,58 +122,13 @@ 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 */
+/** Local mirrors of one remote host. */
 function mirrorRootFor(host, user, port) {
   const tag = [host, user, port].filter(Boolean).join('-').replace(/[^a-zA-Z0-9._-]/g, '_')
   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). 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. */
+/** Local mirror dir for a specific remote path (idempotent → returns same dir). */
 function mirrorDirFor(remotePath, host, user, port) {
   const base = remotePathBase(remotePath)
   const root = mirrorRootFor(host, user, port)
@@ -286,8 +141,6 @@ function mirrorDirFor(remotePath, host, user, port) {
   } 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))
 }
@@ -303,125 +156,48 @@ function ensureMirror(remotePath, host, user, port) {
   return dir
 }
 
-/** 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 */ }
-    }
+/** 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 */ }
   }
-  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,
-    () => [],
-  )
-  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 = 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)
+/** One-time migration of pre-0.6 data (~/.dsh/remote-workspaces) into DSH_HOME.
+ * Only runs when the harness is on its DEFAULT home: an explicitly-set DSH_HOME
+ * pointing elsewhere means ~/.dsh belongs to another installation — migrating
+ * would RENAME that other installation's live data out from under it. */
+function migrateLegacyData() {
+  const env = process.env.DSH_HOME
+  if (env && String(env).trim() && path.resolve(String(env).trim()) !== path.join(homedir(), '.dsh')) return
+  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 {
-      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)
-      try { utimesSync(lp, new Date(st.mtime * 1000), new Date(st.mtime * 1000)) } catch {}
-      stats.files++
-      stats.touched.push(rp)
-    } catch {
-      /* skip unreadable */
+      renameSync(legacy, target)
+    } catch (err) {
+      if (err.code !== 'EXDEV') throw err
+      copyDirSync(legacy, target)
     }
-  })
-  return stats
-}
-
-/** 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')
-  const stats = { files: 0, dirs: 0, skippedUnchanged: 0, skippedLarge: 0, pushed: [] }
-
-  for (const e of entries) {
-    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
+  } catch {
+    // Migration is best-effort: a fresh registry is created on next save.
   }
-  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 = 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)
-      stats.files++
-      stats.pushed.push(rp)
-    } catch {
-      /* skip unreadable / unwritable */
-    }
-  })
-  return stats
 }
 
 // ── persistent multi-machine registry ─────────────────────────────────────
 const MACHINES_FILE = 'machines.json'
 const machinesFile = () => path.join(remoteWorkspacesRoot(), MACHINES_FILE)
+const secretsDir = () => path.join(remoteWorkspacesRoot(), '.secrets')
+const forwardsFile = () => path.join(remoteWorkspacesRoot(), 'forwards.json')
+const auditFile = () => path.join(remoteWorkspacesRoot(), 'audit.log')
+const ignoreFile = () => path.join(remoteWorkspacesRoot(), '.dsh-remote-ignore')
+
 function loadMachines() {
   try {
     const j = JSON.parse(readFileSync(machinesFile(), 'utf8'))
@@ -435,8 +211,10 @@ function saveMachines(list, currentId) {
 }
 function sanitizeMachine(m) {
   if (!m) return m
-  const { password, ...rest } = m
-  return { ...rest, passwordSet: !!(m.password && m.password.length) }
+  const { password, proxy, ...rest } = m
+  const out = { ...rest, passwordSet: !!(m.password && m.password.length) }
+  if (proxy) out.proxy = { ...proxy, password: proxy.password ? '' : undefined, passwordSet: !!(proxy.password && proxy.password.length) }
+  return out
 }
 /** Apply a machine's fields onto the live config object (pool + tools read it). */
 function applyMachine(config, m) {
@@ -448,14 +226,17 @@ function applyMachine(config, m) {
   config.privateKeyPath = m.privateKeyPath || ''
   config.passphrase = m.passphrase || ''
   config.workspace = m.workspace || (config.workspace || '')
+  if (m.hostKeyMode) config.hostKeyMode = m.hostKeyMode
+  if (typeof m.useAgent === 'boolean') config.useAgent = m.useAgent
+  if (typeof m.keyboardInteractive === 'boolean') config.keyboardInteractive = m.keyboardInteractive
+  config.proxy = m.proxy && m.proxy.host ? m.proxy : undefined
 }
 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) ──────
+// ── host-key registry (TOFU) ──────────────────────────────────────────────
 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'))
@@ -464,40 +245,7 @@ function loadKnownHosts() {
   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. */
+/** Build an ssh2 `hostVerifier` bound to the current config. */
 function createHostKeyGuard(config) {
   const id = () => `${config.host}:${config.port}`
   const mode = config.hostKeyMode === 'verify' || config.hostKeyMode === 'off'
@@ -543,106 +291,23 @@ function isHostKeyKnown(host, port) {
   return Object.prototype.hasOwnProperty.call(loadKnownHosts(), `${host}:${port}`)
 }
 
-// ── SSH pool (key OR password) ──────────────────────────────────────────────
-
-/**
- * Wrap a raw ssh2 SFTP handle so a stuck server can never hang a tool call:
- * every method is bounded by the configured command timeout, and path args
- * are normalized via toSftpPath() so Windows remotes (drive-letter paths)
- * work too.
- */
-function wrapSftp(client, sftp, config) {
-  const withTimeout = (fn) => (...args) =>
-    new Promise((r2, j2) => {
-      const timer = setTimeout(() => j2(new Error('sftp operation timed out')), 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)
-  return {
-    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),
-  }
-}
-
-/**
- * Run one exec stream to completion: collects stdout/stderr (bounded), settles
- * on channel close or the configured command timeout. On timeout the remote
- * command gets SIGTERM and the channel is hard-closed so a runaway process
- * cannot keep holding the SSH connection.
- */
-function runStream(client, stream, config, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    let stdout = ''
-    let stderr = ''
-    let settled = false
-    let exitCode = null
-    let exitSignal = null
-    const hardCap = Math.max(config.maxOutputChars * 4, 1024 * 1024)
-    const settle = () => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      resolve({
-        code: exitCode,
-        signal: exitSignal,
-        stdout: truncate(stdout, config.maxOutputChars),
-        stderr: truncate(stderr, config.maxOutputChars),
-      })
-    }
-    const timer = setTimeout(() => {
-      if (settled) return
-      exitCode = -1
-      exitSignal = 'TIMEOUT'
-      // Kill the remote command (SIGTERM) rather than just dropping the
-      // channel, so a runaway process cannot keep running and holding
-      // the SSH connection after we've given up on its output. The hard
-      // close below frees the channel even if the process ignores it.
-      try {
-        if (typeof stream.signal === 'function') stream.signal('SIGTERM')
-      } catch {}
-      const hardClose = setTimeout(() => {
-        try { stream.close() } catch {}
-      }, 800)
-      if (typeof hardClose.unref === 'function') hardClose.unref()
-      settle()
-    }, timeoutMs || config.commandTimeoutMs)
-    stream.on('close', (code, signal) => {
-      if (settled) return
-      exitCode = code
-      exitSignal = signal
-      settle()
-    })
-    stream.on('data', (d) => {
-      if (stdout.length < hardCap) stdout += d
-    })
-    stream.stderr.on('data', (d) => {
-      if (stderr.length < hardCap) stderr += d
-    })
-    stream.on('error', (e) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      reject(new Error('ssh stream error: ' + ((e && e.message) || e)))
-    })
-  })
-}
+// ── SSH pool (key / password / agent / keyboard-interactive / proxy) ──────
 
 class SshPool {
   constructor(config) {
     this.config = config
     this.client = null
     this.connecting = null
+    this.proxyPool = null
     // Generational token: bumped on every target change / close so a stale
     // in-flight connect can never hand this pool a connection to an old host.
     this.epoch = 0
+    /** Optional async resolver for a machine-stored (keychain) password. */
+    this.passwordResolver = null
+    /** Optional hook called with the live client after a successful connect. */
+    this.onReady = null
+    /** Optional hook called when the pool closes. */
+    this.onCloseHook = null
   }
 
   resolveKeyPath() {
@@ -652,8 +317,7 @@ class SshPool {
     return p
   }
 
-  /** Configure (and reconnect with) a new target. Returns this pool for chaining. */
-  setTarget({ host, port, username, password, privateKeyPath, passphrase, workspace }) {
+  setTarget({ host, port, username, password, privateKeyPath, passphrase, workspace, useAgent, keyboardInteractive, proxy, hostKeyMode }) {
     if (host !== undefined) this.config.host = String(host)
     if (port !== undefined && Number(port)) this.config.port = Number(port)
     if (username !== undefined) this.config.username = String(username)
@@ -661,6 +325,10 @@ class SshPool {
     if (privateKeyPath !== undefined) this.config.privateKeyPath = String(privateKeyPath)
     if (passphrase !== undefined) this.config.passphrase = String(passphrase)
     if (workspace !== undefined) this.config.workspace = String(workspace)
+    if (useAgent !== undefined) this.config.useAgent = !!useAgent
+    if (keyboardInteractive !== undefined) this.config.keyboardInteractive = !!keyboardInteractive
+    if (proxy !== undefined) this.config.proxy = proxy
+    if (hostKeyMode !== undefined) this.config.hostKeyMode = String(hostKeyMode)
     this.close()
     return this
   }
@@ -674,42 +342,49 @@ class SshPool {
     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
   }
 
-  /**
-   * Drop the cached client and force a fresh connection on the next call.
-   * Called when a channel open fails (e.g. "Channel open failure: open
-   * failed") — the pooled SSH connection is usually dead server-side while
-   * keepalive has not yet noticed, and reusing it keeps failing. The epoch
-   * bump orphans any in-flight connect; the client is ended so ssh2 frees
-   * its sockets.
-   */
-  invalidate() {
-    this.epoch++
-    const client = this.client
-    this.client = null
-    const pending = this.connecting
-    this.connecting = null
-    if (pending && typeof pending.catch === 'function') {
-      try { pending.catch(() => {}) } catch {}
+  async _doConnect(epoch) {
+    const isCurrent = () => this.epoch === epoch
+    const guard = createHostKeyGuard(this.config)
+    const client = new Client()
+    let settled = false
+    const fail = (err) => {
+      if (settled) return
+      settled = true
+      if (isCurrent() && this.client === client) this.client = null
+      throw guard.lastError ? new Error(guard.lastError) : err
     }
-    if (client) {
-      try { client.end() } catch {}
+
+    // Proxy jump: SSH to the bastion first, then tunnel to the target through it.
+    let sock = null
+    const proxyCfg = this.config.proxy
+    if (proxyCfg && proxyCfg.host) {
+      try {
+        this.proxyPool = new SshPool({
+          ...this.config,
+          host: proxyCfg.host,
+          port: Number(proxyCfg.port) || 22,
+          username: proxyCfg.username || this.config.username || 'root',
+          password: proxyCfg.password || '',
+          privateKeyPath: proxyCfg.privateKeyPath || '',
+          passphrase: proxyCfg.passphrase || '',
+          proxy: undefined,
+        })
+        const pclient = await this.proxyPool.connect()
+        if (!isCurrent()) throw new Error('ssh target changed during proxy connect')
+        sock = await new Promise((res, rej) => {
+          pclient.forwardOut('127.0.0.1', 0, this.config.host, this.config.port, (e, ch) => (e ? rej(new Error('proxy forward to target failed: ' + ((e && e.message) || e))) : res(ch)))
+        })
+      } catch (err) {
+        return fail(err)
+      }
     }
-  }
 
-  _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) => {
+      const rejectOnce = (err) => {
         if (settled) return
         settled = true
         if (isCurrent() && this.client === client) this.client = null
@@ -719,113 +394,244 @@ class SshPool {
         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)
+        if (this.onReady) { try { this.onReady(client) } catch {} }
       })
-      client.on('error', fail)
+      client.on('error', (e) => rejectOnce(e))
       client.on('close', () => {
         if (isCurrent() && this.client === client) this.client = null
-        fail(new Error('ssh connection closed'))
+        rejectOnce(new Error('ssh connection closed'))
       })
 
-      const opts = {
-        host: this.config.host,
-        port: this.config.port,
-        username: this.config.username,
-        readyTimeout: this.config.connectTimeoutMs,
-        keepaliveInterval: 15000,
-        keepaliveCountMax: 3,
-        hostVerifier: (key) => guard.verifier(key),
-      }
-      if (this.config.password) {
-        opts.password = this.config.password
-      } else {
-        const keyPath = this.resolveKeyPath()
-        if (!keyPath) {
-          return fail(new Error('no credentials: set a password or a privateKeyPath to connect'))
+      const buildOpts = async () => {
+        const opts = {
+          host: this.config.host,
+          port: this.config.port,
+          username: this.config.username,
+          readyTimeout: this.config.connectTimeoutMs,
+          keepaliveInterval: 15000,
+          keepaliveCountMax: 3,
+          hostVerifier: (key) => guard.verifier(key),
         }
-        let key
-        try {
-          key = readFileSync(keyPath)
-        } catch (err) {
-          return fail(new Error(`cannot read private key "${keyPath}": ${err && err.message}`))
+        if (sock) opts.sock = sock
+        if (this.config.useAgent) {
+          const sockPath = process.env.SSH_AUTH_SOCK
+          if (sockPath) opts.agent = sockPath
+        }
+        let password = this.config.password || ''
+        if (!password && this.passwordResolver) {
+          try { password = (await this.passwordResolver()) || '' } catch {}
+        }
+        if (password) {
+          opts.password = password
+          opts.tryKeyboard = true
+        } else if (this.config.keyboardInteractive && !this.config.privateKeyPath) {
+          opts.tryKeyboard = true
+        }
+        if (this.config.privateKeyPath) {
+          const keyPath = this.resolveKeyPath()
+          if (!keyPath) {
+            throw new Error('no credentials: set a password or a privateKeyPath to connect')
+          }
+          let key
+          try {
+            key = readFileSync(keyPath)
+          } catch (err) {
+            throw new Error(`cannot read private key "${keyPath}": ${err && err.message}`)
+          }
+          opts.privateKey = key
+          opts.passphrase = this.config.passphrase || undefined
+        } else if (!password && !opts.agent) {
+          throw new Error('no credentials: set a password, a privateKeyPath, or enable useAgent to connect')
         }
-        opts.privateKey = key
-        opts.passphrase = this.config.passphrase || undefined
+        return opts
       }
-      client.connect(opts)
+
+      buildOpts().then(
+        (opts) => {
+          if (opts.tryKeyboard) {
+            client.on('keyboard-interactive', (name, instructions, lang, prompts, finish) => {
+              finish(prompts.map(() => this.config.password || ''))
+            })
+          }
+          client.connect(opts)
+        },
+        (err) => rejectOnce(err),
+      )
     })
   }
 
-  /** Run one remote command; resolves { code, signal, stdout, stderr }. */
-  exec(command, timeoutMs) {
+  /** Run one remote command; resolves { code, signal, stdout, stderr }.
+   * Accepts `exec(cmd, timeoutMs)` (legacy) or `exec(cmd, {timeoutMs, pty, env})`. */
+  exec(command, timeoutMsOrOpts) {
+    const opts = timeoutMsOrOpts && typeof timeoutMsOrOpts === 'object' ? timeoutMsOrOpts : { timeoutMs: timeoutMsOrOpts }
+    const timeoutMs = opts.timeoutMs || this.config.commandTimeoutMs
     return this.connect().then(
       (client) =>
         new Promise((resolve, reject) => {
-          client.exec(command, (err, stream) => {
-            if (err) {
-              // Same dead-connection recovery as sftp(): a channel open
-              // failure means the pooled connection is stale — drop it and
-              // retry ONCE on a fresh connection.
-              if (/channel open failure|open failed/i.test(String((err && err.message) || err))) {
-                this.invalidate()
-                return this.connect().then(
-                  (fresh) => fresh.exec(command, (err2, stream2) => {
-                    if (err2) return reject(new Error('ssh exec failed: ' + ((err2 && err2.message) || err2)))
-                    resolve(runStream(fresh, stream2, this.config, timeoutMs))
-                  }),
-                  (e2) => reject(new Error('ssh exec failed (reconnect): ' + ((e2 && e2.message) || e2))),
-                )
+          let retried = false
+          const runOn = (c) => {
+            const execOpts = {}
+            if (opts.pty) execOpts.pty = true
+            if (opts.env && typeof opts.env === 'object') execOpts.env = opts.env
+            c.exec(command, execOpts, (err, stream) => {
+              if (err) {
+                // Channel-open failure usually means the pooled connection died
+                // server-side (idle timeout / network reset) while keepalive
+                // hadn't noticed. Drop it and retry ONCE on a fresh connection.
+                if (!retried && /channel open failure|open failed/i.test(String((err && err.message) || err))) {
+                  retried = true
+                  this.invalidate()
+                  return this.connect().then(
+                    (fresh) => runOn(fresh),
+                    (e2) => reject(new Error('ssh exec failed (reconnect): ' + ((e2 && e2.message) || e2))),
+                  )
+                }
+                return reject(new Error('ssh exec failed: ' + ((err && err.message) || err)))
               }
-              return reject(new Error('ssh exec failed: ' + ((err && err.message) || err)))
-            }
-            resolve(runStream(client, stream, this.config, timeoutMs))
-          })
+              let stdout = ''
+              let stderr = ''
+              let settled = false
+              let exitCode = null
+              let exitSignal = null
+              const hardCap = Math.max(this.config.maxOutputChars * 4, 1024 * 1024)
+              const settle = () => {
+                if (settled) return
+                settled = true
+                clearTimeout(timer)
+                resolve({
+                  code: exitCode,
+                  signal: exitSignal,
+                  stdout: truncate(stdout, this.config.maxOutputChars),
+                  stderr: truncate(stderr, this.config.maxOutputChars),
+                })
+              }
+              const timer = setTimeout(() => {
+                if (settled) return
+                exitCode = -1
+                exitSignal = 'TIMEOUT'
+                // Kill the remote command (SIGTERM) rather than just dropping the
+                // channel, so a runaway process cannot keep running and holding
+                // the SSH connection after we've given up on its output.
+                try {
+                  if (typeof stream.signal === 'function') stream.signal('SIGTERM')
+                } catch {}
+                const hardClose = setTimeout(() => {
+                  try { stream.close() } catch {}
+                }, 800)
+                if (typeof hardClose.unref === 'function') hardClose.unref()
+                settle()
+              }, timeoutMs)
+              stream.on('close', (code, signal) => {
+                if (settled) return
+                exitCode = code
+                exitSignal = signal
+                settle()
+              })
+              stream.on('data', (d) => {
+                if (stdout.length < hardCap) stdout += d
+              })
+              stream.stderr.on('data', (d) => {
+                if (stderr.length < hardCap) stderr += d
+              })
+              stream.on('error', (e) => {
+                if (settled) return
+                settled = true
+                clearTimeout(timer)
+                reject(new Error('ssh stream error: ' + ((e && e.message) || e)))
+              })
+            })
+          }
+          runOn(client)
         }),
     )
   }
 
-  /** 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. */
+  /** Resolve a promisified SFTP client. All paths normalized via toSftpPath(). */
   sftp() {
     return this.connect().then(
       (client) =>
         new Promise((resolve, reject) => {
-          client.sftp((err, sftp) => {
-            if (err) {
-              // Channel open failure usually means the pooled connection is
-              // dead server-side (idle timeout / network reset) while
-              // keepalive hasn't noticed yet. Drop it and retry ONCE on a
-              // fresh connection; a persistent error still rejects.
-              if (/channel open failure|open failed/i.test(String((err && err.message) || err))) {
-                this.invalidate()
-                return this.connect().then(
-                  (fresh) => fresh.sftp((err2, sftp2) => {
-                    if (err2) return reject(new Error('ssh sftp failed: ' + ((err2 && err2.message) || err2)))
-                    resolve(wrapSftp(fresh, sftp2, this.config))
-                  }),
-                  (e2) => reject(new Error('ssh sftp failed (reconnect): ' + ((e2 && e2.message) || e2))),
-                )
+          let retried = false
+          const runOn = (c) => {
+            c.sftp((err, sftp) => {
+              if (err) {
+                // Same dead-connection recovery as exec(): a channel open
+                // failure means the pooled connection is stale — drop it and
+                // retry ONCE on a fresh connection.
+                if (!retried && /channel open failure|open failed/i.test(String((err && err.message) || err))) {
+                  retried = true
+                  this.invalidate()
+                  return this.connect().then(
+                    (fresh) => runOn(fresh),
+                    (e2) => reject(new Error('ssh sftp failed (reconnect): ' + ((e2 && e2.message) || e2))),
+                  )
+                }
+                return reject(new Error('ssh sftp failed: ' + ((err && err.message) || err)))
               }
-              return reject(new Error('ssh sftp failed: ' + ((err && err.message) || err)))
-            }
-            resolve(wrapSftp(client, sftp, this.config))
-          })
+              const withTimeout = (fn) => (...args) =>
+                new Promise((r2, j2) => {
+                  const timer = setTimeout(() => j2(new Error('sftp operation timed out')), this.config.commandTimeoutMs)
+                  const done = (e, v) => {
+                    clearTimeout(timer)
+                    e ? j2(e) : r2(v)
+                  }
+                  try { fn(...args, done) } catch (e) { clearTimeout(timer); j2(e) }
+                })
+              const P = (p) => toSftpPath(p)
+              resolve({
+                readdir: (dir) => withTimeout((d, cb) => sftp.readdir(d, cb))(P(dir)),
+                stat: (p) => withTimeout((d, cb) => sftp.stat(d, cb))(P(p)),
+                lstat: (p) => withTimeout((d, cb) => sftp.lstat(d, cb))(P(p)),
+                mkdir: (dir) => withTimeout((d, cb) => sftp.mkdir(d, cb))(P(dir)),
+                rmdir: (dir) => withTimeout((d, cb) => sftp.rmdir(d, cb))(P(dir)),
+                unlink: (p) => withTimeout((d, cb) => sftp.unlink(d, cb))(P(p)),
+                rename: (p, d) => withTimeout((a, b, cb) => sftp.rename(a, b, cb))(P(p), P(d)),
+                realpath: (p) => withTimeout((d, cb) => sftp.realpath(d, cb))(P(p)),
+                readFile: (p) => withTimeout((d, cb) => sftp.readFile(d, cb))(P(p)),
+                writeFile: (p, data) => withTimeout((d, data2, cb) => sftp.writeFile(d, data2, cb))(P(p), data),
+                fastGet: (p, lp) => withTimeout((d, l, cb) => sftp.fastGet(d, l, cb))(P(p), lp),
+                fastPut: (p, lp) => withTimeout((d, l, cb) => sftp.fastPut(d, l, cb))(P(p), lp),
+              })
+            })
+          }
+          runOn(client)
         }),
     )
   }
 
+  /**
+   * Drop the cached client and force a fresh connection on the next call.
+   * Called when a channel open fails (e.g. "Channel open failure: open
+   * failed") — the pooled SSH connection is usually dead server-side while
+   * keepalive has not yet noticed, and reusing it keeps failing. The epoch
+   * bump orphans any in-flight connect; the client is ended so ssh2 frees
+   * its sockets.
+   */
+  invalidate() {
+    this.epoch++
+    const client = this.client
+    this.client = null
+    const pending = this.connecting
+    this.connecting = null
+    if (pending && typeof pending.catch === 'function') {
+      try { pending.catch(() => {}) } catch {}
+    }
+    if (this.proxyPool) {
+      try { this.proxyPool.close() } catch {}
+      this.proxyPool = null
+    }
+    if (client) {
+      try { client.end() } catch {}
+    }
+  }
+
   close() {
-    // 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
@@ -834,67 +640,218 @@ class SshPool {
     if (pending && typeof pending.catch === 'function') {
       try { pending.catch(() => {}) } catch {}
     }
+    if (this.proxyPool) {
+      try { this.proxyPool.close() } catch {}
+      this.proxyPool = null
+    }
     if (client) {
       try {
         client.end()
       } catch {}
     }
+    if (this.onCloseHook) {
+      try { this.onCloseHook() } catch {}
+    }
   }
 }
 
-// ── helper: run + text ─────────────────────────────────────────────────────
+// ── encoding helpers ───────────────────────────────────────────────────────
+
+function decodeBuf(buf, enc) {
+  const e = enc && !/^utf-?8$/i.test(String(enc)) ? String(enc).toLowerCase() : null
+  return e ? iconv.decode(buf, e) : buf.toString('utf8')
+}
+function encodeText(s, enc) {
+  const e = enc && !/^utf-?8$/i.test(String(enc)) ? String(enc).toLowerCase() : null
+  return e ? iconv.encode(String(s), e) : Buffer.from(String(s), 'utf8')
+}
+
+// ── apply ─────────────────────────────────────────────────────────────────
 
 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
   const machineIndex = (id) => machines.findIndex((m) => m.id === id)
-  const currentMachine = () => {
+
+  /** The machine the pool is currently bound to: an ephemeral tool connection
+   * (rw_connect save:false) wins, then the stored current, then config default. */
+  let ephemeral = null
+  const activeMachine = () => {
+    if (ephemeral) return ephemeral
     if (store.currentId) {
       const i = machineIndex(store.currentId)
       if (i >= 0) return machines[i]
     }
-    // fall back to config-derived default (host set via cordis config)
     if (config.host) return { id: machineId(), name: config.host, host: config.host, port: config.port, username: config.username, password: config.password, privateKeyPath: config.privateKeyPath, passphrase: config.passphrase }
     return null
   }
-  const setCurrent = (id) => {
+  const currentMachine = activeMachine
+
+  /** Resolve a machine's effective password (keychain backend support). */
+  const machinePassword = async (m) => {
+    if (m && m.password) return m.password
+    if (m && m.credentialBackend && m.credentialBackend !== 'plain') {
+      const p = await getSecret(m.id, secretsDir())
+      if (p) return p
+    }
+    return ''
+  }
+
+  // The pool resolves keychain-stored passwords lazily at connect time.
+  pool.passwordResolver = async () => {
+    const m = activeMachine()
+    return machinePassword(m)
+  }
+
+  const applyActiveMachine = async () => {
+    const m = activeMachine()
+    if (!m || !m.host) return
+    const pw = await machinePassword(m)
+    applyMachine(config, { ...m, password: pw || m.password || '' })
+    pool.setTarget({
+      host: config.host, port: config.port, username: config.username,
+      password: config.password, privateKeyPath: config.privateKeyPath,
+      passphrase: config.passphrase, workspace: config.workspace,
+      useAgent: config.useAgent, keyboardInteractive: config.keyboardInteractive,
+      proxy: config.proxy, hostKeyMode: config.hostKeyMode,
+    })
+  }
+
+  const setCurrent = async (id) => {
     const i = machineIndex(id)
     if (i < 0) return false
     store.currentId = id
+    ephemeral = null
     saveMachines(machines, id)
-    applyMachine(config, machines[i])
-    pool.setTarget({ host: config.host, port: config.port, username: config.username, password: config.password, privateKeyPath: config.privateKeyPath, passphrase: config.passphrase })
+    await applyActiveMachine()
     return true
   }
+
   // If no stored current, adopt a CLI-provided default as the active machine.
   {
     const cur = currentMachine()
-    if (cur && cur.host) applyMachine(config, cur)
+    if (cur && cur.host && !store.currentId) 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). */
+  /** Persist the active workspace on the machine the pool is actually bound to
+   * (fixes the old bug where a tool-connected machine saved its workspace onto
+   * the registry's current machine instead). */
   const persistWorkspace = (p) => {
     config.workspace = p
-    if (store.currentId) {
-      const i = machineIndex(store.currentId)
-      if (i >= 0) {
-        machines[i].workspace = p
+    const m = activeMachine()
+    if (m) {
+      if (store.currentId && m.id === store.currentId && machineIndex(m.id) >= 0) {
+        const rec = machines[machineIndex(m.id)]
+        rec.workspace = p
+        rec.recentWorkspaces = [p, ...(rec.recentWorkspaces || []).filter((x) => x !== p)].slice(0, 8)
         saveMachines(machines, store.currentId)
+      } else if (ephemeral) {
+        ephemeral.workspace = p
       }
     }
   }
 
+  // ── audit log ─────────────────────────────────────────────────────────────
+  const audit = (op, cmd, code) => {
+    if (!config.auditLog) return
+    try {
+      const line = [new Date().toISOString(), `${config.username || '?'}@${config.host || '?'}:${config.port}`, op, code == null ? '-' : String(code), String(cmd || '').replace(/\s+/g, ' ').slice(0, 400)].join(' | ') + '\n'
+      appendFileSync(auditFile(), line, 'utf8')
+    } catch {}
+  }
+  const readAudit = (limit) => {
+    try {
+      const text = readFileSync(auditFile(), 'utf8')
+      const lines = text.split('\n').filter(Boolean)
+      return lines.slice(-Math.max(1, Math.min(Number(limit) || 50, 500)))
+    } catch {
+      return []
+    }
+  }
+
+  // ── ignore rules (defaults + user file) ───────────────────────────────────
+  const ignoreMatcher = () => {
+    try {
+      const fromFile = readFileSync(ignoreFile(), 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+      return compileIgnore(DEFAULT_IGNORE.concat(fromFile))
+    } catch {
+      return compileIgnore(DEFAULT_IGNORE)
+    }
+  }
+
+  // ── task + forward managers ───────────────────────────────────────────────
+  const tasks = new TaskManager()
+  const forwards = new ForwardManager(pool, { file: forwardsFile() })
+  pool.onReady = (client) => forwards.attach(client)
+  pool.onCloseHook = () => forwards.detach()
+
+  // ── auto-push watcher (config.autoPush, default off) ──────────────────────
+  // Watches the local mirror; local edits are pushed back to the remote after a
+  // 3s debounce, honoring ignore rules + the three-way conflict guard (a remote
+  // change is never clobbered — it is recorded as a conflict in the audit log).
+  const autoPushWatchers = new Map() // localDir → { watcher, pending:Set, timer }
+  const flushAutoPush = async (localDir) => {
+    const entry = autoPushWatchers.get(localDir)
+    if (!entry || !entry.pending.size) return
+    const rels = [...entry.pending]
+    entry.pending.clear()
+    const ws = wsPath()
+    if (!ws || mirrorDirFor(ws, config.host, config.username, config.port) !== localDir) return
+    let sftp
+    try { sftp = await pool.sftp() } catch { return }
+    const matcher = ignoreMatcher()
+    const state = loadSyncState(localDir)
+    const next = { ...state }
+    if (rels.includes('*')) {
+      const r = await pushTree(sftp, localDir, ws, { maxFiles: 500, maxFileBytes: config.maxFileBytes, isIgnored: matcher, state: next })
+      Object.assign(next, r.nextState)
+      for (const c of r.stats.conflicts) audit('auto-push-conflict', `push ${c.path}`, 1)
+    } else {
+      for (const rel of rels) {
+        const r = await pushOneFile(sftp, localDir, ws, rel, { maxFileBytes: config.maxFileBytes, isIgnored: matcher, state: next })
+        if (r.status === 'pushed' && r.state) Object.assign(next, r.state)
+        else if (r.status === 'conflict') audit('auto-push-conflict', `push ${rel}`, 1)
+      }
+    }
+    saveSyncState(localDir, next)
+  }
+  const startAutoPush = (localDir) => {
+    if (!config.autoPush || autoPushWatchers.has(localDir)) return
+    const entry = { pending: new Set(), timer: null, watcher: null }
+    const schedule = () => {
+      if (entry.timer) clearTimeout(entry.timer)
+      entry.timer = setTimeout(() => flushAutoPush(localDir), 3000)
+    }
+    const onEvent = (eventType, filename) => {
+      if (!filename) { entry.pending.add('*'); return schedule() }
+      const rel = String(filename).replace(/\\/g, '/')
+      if (rel === '.dsh-remote-meta.json' || rel === '.dsh-remote-sync-state.json' || rel.startsWith('.dsh-remote-sync-state.json.tmp')) return
+      entry.pending.add(rel)
+      schedule()
+    }
+    try {
+      entry.watcher = watch(localDir, { recursive: true }, onEvent)
+    } catch {
+      try { entry.watcher = watch(localDir, onEvent) } catch { return }
+    }
+    autoPushWatchers.set(localDir, entry)
+  }
+  ctx.effect(() => () => {
+    for (const e of autoPushWatchers.values()) {
+      if (e.timer) clearTimeout(e.timer)
+      try { e.watcher && e.watcher.close() } catch {}
+    }
+    autoPushWatchers.clear()
+  }, 'dsh-remote.autopush')
+
   const run = async (cmd, opts = {}) => {
-    const res = await pool.exec(cmd, opts.timeoutMs)
+    const res = await pool.exec(cmd, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {})
     const parts = []
     if (res.stdout) parts.push(res.stdout.replace(/\s+$/, ''))
     if (res.stderr) parts.push('-- stderr --\n' + res.stderr.replace(/\s+$/, ''))
@@ -905,13 +862,9 @@ export async function apply(ctx, config) {
     return text
   }
 
-  /** 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) => {
+  /** Structured listing: name + type + size + mtime + mode (SFTP protocol-level,
+   * works on any remote: POSIX / cmd.exe / PowerShell). */
+  const listDirStructured = async (p) => {
     const target = normalizeRemotePath(p || '/')
     let sftp
     try {
@@ -919,7 +872,7 @@ export async function apply(ctx, config) {
     } catch (err) {
       throw new Error('browse failed: ' + ((err && err.message) || err))
     }
-    let list = []
+    let list
     try {
       list = await sftp.readdir(target)
     } catch (err) {
@@ -931,14 +884,22 @@ export async function apply(ctx, config) {
       const name = String(e.filename)
       if (name === '.' || name === '..' || !name) continue
       const a = e.attrs || {}
+      let type
       if (a.isSymbolicLink && a.isSymbolicLink()) {
-        items.push({ type: 'symlink', name })
-        symIdx.push(items.length - 1)
+        type = 'symlink'
+        symIdx.push(items.length)
       } else if (a.isDirectory && a.isDirectory()) {
-        items.push({ type: 'dir', name })
+        type = 'dir'
       } else {
-        items.push({ type: 'file', name })
+        type = 'file'
       }
+      items.push({
+        type,
+        name,
+        size: typeof a.size === 'number' ? a.size : 0,
+        mtime: typeof a.mtime === 'number' ? a.mtime : 0,
+        mode: typeof a.mode === 'number' ? a.mode.toString(8) : '',
+      })
     }
     // Resolve symlink-to-dir vs symlink-to-file (bounded, failure-tolerant).
     if (symIdx.length) {
@@ -953,9 +914,6 @@ export async function apply(ctx, config) {
     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 {
@@ -967,9 +925,35 @@ export async function apply(ctx, config) {
     }
   }
 
-  // ── remote workspace state ────────────────────────────────────────────────
+  /** Recursive remote delete (bounded): unlink files bottom-up, then rmdir. */
+  const removeRemoteTree = async (sftp, p, maxFiles = 2000) => {
+    let removed = 0
+    const walk = async (dir) => {
+      if (removed >= maxFiles) return
+      let entries = []
+      try { entries = (await sftp.readdir(dir)) || [] } catch { return }
+      for (const e of entries) {
+        if (removed >= maxFiles) return
+        const name = String(e.filename)
+        if (name === '.' || name === '..') continue
+        const fp = joinRemotePath(dir, name)
+        const isDir = !!(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory())
+        if (isDir) await walk(fp)
+        else {
+          try { await sftp.unlink(fp); removed++ } catch {}
+        }
+      }
+      try { await sftp.rmdir(dir); removed++ } catch { /* already gone or non-empty */ }
+    }
+    await walk(p)
+    return removed
+  }
 
+  // ── remote workspace state ────────────────────────────────────────────────
   const wsPath = () => (config.workspace || '').trim()
+  if (config.autoPush && wsPath()) {
+    startAutoPush(mirrorDirFor(wsPath(), config.host, config.username, config.port))
+  }
   const status = () => ({
     host: config.host,
     port: config.port,
@@ -978,46 +962,52 @@ export async function apply(ctx, config) {
     workspace: wsPath(),
     localMirror: wsPath() ? mirrorDirFor(wsPath(), config.host, config.username, config.port) : '',
     currentId: store.currentId || null,
+    activeSource: ephemeral ? 'ephemeral' : (store.currentId ? 'machine' : (config.host ? 'config' : 'none')),
     machines: machines.map(sanitizeMachine),
     hostKeyMode: config.hostKeyMode === 'verify' || config.hostKeyMode === 'off' ? config.hostKeyMode : 'accept-new',
     hostKeyKnown: config.host ? isHostKeyKnown(config.host, config.port) : false,
+    forwards: forwards.list(),
+    auditEnabled: !!config.auditLog,
+    backend: platformBackend(),
   })
 
   // ── tools ─────────────────────────────────────────────────────────────────
 
-  const renderErr = (err) => ({
-    kind: 'error',
-    text: String((err && err.message) || err),
-  })
+  const textOut = {
+    schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
+    render: (_a, v) => [{ type: 'text', text: v.text }],
+  }
+  const okOut = {
+    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 ? 'ok' : 'failed') }],
+  }
 
   const tools = [
     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 an rw_* call fails to check connectivity.',
+        'Show the remote environment: host/user/port, connection health, current remote workspace path, active port forwards. 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 } } },
-        render: (_a, v) => [{ type: 'text', text: v.text }],
-      },
+      output: textOut,
       async execute() {
         const s = status()
         const lines = [
-          `Remote host: ${s.username || '<user>'}@${s.host || '<host>'}:${s.port}`,
+          `Remote host: ${s.username || '<user>'}@${s.host || '<host>'}:${s.port}${s.activeSource !== 'machine' ? ` (source: ${s.activeSource})` : ''}`,
           `Current remote workspace: ${s.workspace || '(none — call rw_pick_workspace to set one)'}`,
           `Local mirror: ${s.localMirror || '(none)'}`,
           `Connected: ${s.connected ? 'yes' : 'no'}`,
+          `Active forwards: ${s.forwards.filter((f) => f.active).length} / ${s.forwards.length}`,
+          `Host key: ${s.hostKeyKnown ? 'trusted' : 'not yet trusted'} (mode=${s.hostKeyMode})`,
           '',
         ]
         if (s.host && s.workspace) {
           try {
-            // `echo ok` only — the `;`-joined probes broke on cmd.exe remotes.
-            const res = await pool.exec('echo ok', Math.min(config.commandTimeoutMs, 8000))
+            const res = await pool.exec('echo ok', { timeoutMs: 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())
           } catch (err) {
-            lines.push('Ping: FAILED — ' + ((err && err.message) || err))
+            lines.push('Ping: FAILED — ' + friendlyMessage(err, s))
           }
         } else {
           lines.push('No host + workspace configured — call rw_connect with a host to get started.')
@@ -1029,34 +1019,62 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_connect',
       description:
-        'Connect SSH to a remote host for remote workspace work. Provide host (required), user, optional password or privateKeyPath/port. Once connected, call rw_pick_workspace to pick the workspace directory this session should work in.',
+        'Connect SSH to a remote host for remote workspace work. Provide host (required), user, optional password or privateKeyPath/port. Defaults to saving the machine to the registry (save=false keeps it as a temporary connection). Once connected, call rw_pick_workspace to pick the workspace directory this session should work in.',
       parameters: {
         host: { type: 'string', required: true, description: 'Remote host IP or hostname' },
         username: { type: 'string', description: 'SSH user (default from config or root)' },
         port: { type: 'integer', description: 'SSH port (default 22)' },
         password: { type: 'string', description: 'SSH password (prefer SSH key when possible)' },
         privateKeyPath: { type: 'string', description: 'Absolute private-key path' },
+        save: { type: 'boolean', description: 'Save this machine to the registry and make it current (default true)' },
       },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
-      },
+      output: textOut,
       async execute(args) {
         const host = String(args.host || '').trim()
         if (!host) throw new Error('rw_connect: host is required')
-        pool.setTarget({
+        const user = args.username || config.username || 'root'
+        const port = Number(args.port) || undefined
+        const rec = {
           host,
-          username: args.username || config.username || 'root',
-          port: args.port || undefined,
-          password: args.password !== undefined ? args.password : undefined,
-          privateKeyPath: args.privateKeyPath || undefined,
-        })
+          port: port || 22,
+          username: user,
+          password: args.password !== undefined ? String(args.password) : '',
+          privateKeyPath: args.privateKeyPath || '',
+        }
+        if (args.save !== false) {
+          // Upsert into the registry and make it the current machine so the
+          // settings UI and the tools always agree on who is active.
+          const i = machines.findIndex((m) => m.host === rec.host && m.username === rec.username && Number(m.port) === rec.port)
+          if (i >= 0) {
+            machines[i] = { ...machines[i], ...rec, id: machines[i].id, password: rec.password || machines[i].password || '' }
+            store.currentId = machines[i].id
+            saveMachines(machines, store.currentId)
+          } else {
+            const id = machineId()
+            machines.push({ id, name: host, ...rec })
+            store.currentId = id
+            saveMachines(machines, store.currentId)
+          }
+          ephemeral = null
+          await applyActiveMachine()
+        } else {
+          ephemeral = { id: machineId(), name: host, ...rec }
+          pool.setTarget({
+            host, port: port || 22, username: user,
+            password: rec.password, privateKeyPath: rec.privateKeyPath,
+            workspace: config.workspace,
+          })
+        }
         try {
-          const res = await pool.exec('echo ok', 8000)
-          if (res.code !== 0 && !res.stdout) return { text: 'connect failed: ' + (res.stderr || 'exit ' + res.code) }
+          const res = await pool.exec('echo ok', { timeoutMs: 8000 })
+          if (res.code !== 0 && !res.stdout) {
+            audit('connect', `connect ${user}@${host}:${port || 22}`, res.code)
+            return { text: 'connect failed: ' + (res.stderr || 'exit ' + res.code) }
+          }
+          audit('connect', `connect ${user}@${host}:${port || 22}`, 0)
           return { text: `Connected to ${host} as ${config.username}.\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
         } catch (err) {
-          throw err
+          throw new Error(friendlyMessage(err, { host, port }))
         }
       },
     }),
@@ -1068,10 +1086,7 @@ export async function apply(ctx, config) {
       parameters: {
         path: { type: 'string', required: true, description: 'Absolute remote directory path, e.g. /home/dev/code/project' },
       },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
-      },
+      output: textOut,
       async execute(args) {
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_pick_workspace: path must be an absolute directory')
@@ -1079,6 +1094,7 @@ export async function apply(ctx, config) {
         if (!ok) return { text: `not a directory (or missing) on ${p}` }
         persistWorkspace(p)
         const local = ensureMirror(p, config.host, config.username, config.port)
+        startAutoPush(local)
         return {
           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.`,
         }
@@ -1088,15 +1104,15 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_sync',
       description:
-        'Download the current remote workspace into its local mirror directory over SFTP (bounded). Makes the remote files visible/editable locally so the DSH native workspace / fs tools can operate on them.',
+        'Download the current remote workspace into its local mirror directory over SFTP (bounded, three-way conflict-aware). Makes the remote files visible/editable locally so the DSH native workspace / fs tools can operate on them. Conflicts (both sides modified) are reported and never overwritten; use force=true to override.',
       parameters: {
         depth: { type: 'integer', description: 'Max directory depth to mirror (default 5)' },
         maxFiles: { type: 'integer', description: 'Max files to download (default 500)' },
+        dryRun: { type: 'boolean', description: 'Compute the plan without downloading (default false)' },
+        force: { type: 'boolean', description: 'Overwrite conflicting files (default false)' },
+        async: { type: 'boolean', description: 'Run in the background and return a task id (default false)' },
       },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
-      },
+      output: textOut,
       async execute(args) {
         const p = wsPath()
         if (!p) throw new Error('rw_sync: no remote workspace set — call rw_pick_workspace first')
@@ -1104,241 +1120,446 @@ export async function apply(ctx, config) {
         mkdirSync(local, { recursive: true })
         const depth = Math.min(Math.max(Number(args.depth) || 5, 1), 8)
         const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
-        let sftp
+        const isIgnored = ignoreMatcher()
+        const body = { depth, maxFiles, dryRun: !!args.dryRun, force: !!args.force, isIgnored }
+        const runSync = async () => {
+          let sftp
+          try {
+            sftp = await pool.sftp()
+          } catch (err) {
+            throw new Error('sftp unavailable: ' + ((err && err.message) || err))
+          }
+          const state = loadSyncState(local)
+          const { stats, nextState } = await syncTree(sftp, p, local, { ...body, state, maxFileBytes: config.maxFileBytes })
+          if (!args.dryRun) saveSyncState(local, nextState)
+          let text = `${args.dryRun ? 'WOULD download' : 'Downloaded'} ${stats.files} file(s) from ${p} → ${local}${stats.files >= maxFiles ? ' (hit download cap)' : ''}.`
+          if (stats.skippedUnchanged) text += ` ${stats.skippedUnchanged} unchanged.`
+          if (stats.skippedLarge) text += ` ${stats.skippedLarge} too large (over ${config.maxFileBytes} bytes).`
+          if (stats.staleRemote) text += ` ${stats.staleRemote} remote entries gone (kept locally; use rw_push to mirror deletions).`
+          if (stats.conflicts.length) {
+            text += `\n⚠ ${stats.conflicts.length} conflict(s), NOT overwritten:`
+            for (const c of stats.conflicts.slice(0, 10)) text += `\n  ${c.path} — ${c.reason}`
+            if (stats.conflicts.length > 10) text += `\n  … and ${stats.conflicts.length - 10} more`
+            text += '\n(use force=true to override)'
+          }
+          return { text }
+        }
+        if (args.async) {
+          const t = tasks.start('sync', `sync ${p}`, runSync)
+          return { text: `sync started in background: taskId=${t.id} (GET /dsh-remote/task?id=${t.id} for progress)` }
+        }
+        return runSync()
+      },
+    }),
+
+    defineTool({
+      name: 'rw_push',
+      description:
+        'Upload the local mirror of the current remote workspace back to the remote host over SFTP (bounded, three-way conflict-aware). Use after editing files in the local mirror so the remote reflects your changes. Conflicts (both sides modified) are reported and never overwritten; use force=true to override.',
+      parameters: {
+        maxFiles: { type: 'integer', description: 'Max files to upload (default 500)' },
+        dryRun: { type: 'boolean', description: 'Compute the plan without uploading (default false)' },
+        force: { type: 'boolean', description: 'Overwrite conflicting files (default false)' },
+        async: { type: 'boolean', description: 'Run in the background and return a task id (default false)' },
+      },
+      output: textOut,
+      async execute(args) {
+        const p = wsPath()
+        if (!p) throw new Error('rw_push: no remote workspace set — call rw_pick_workspace first')
+        const local = mirrorDirFor(p, config.host, config.username, config.port)
+        if (!existsSync(local)) throw new Error(`rw_push: local mirror does not exist — run rw_sync first (${local})`)
+        const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
+        const isIgnored = ignoreMatcher()
+        const body = { maxFiles, dryRun: !!args.dryRun, force: !!args.force, isIgnored }
+        const runPush = async () => {
+          let sftp
+          try {
+            sftp = await pool.sftp()
+          } catch (err) {
+            throw new Error('sftp unavailable: ' + ((err && err.message) || err))
+          }
+          const state = loadSyncState(local)
+          const { stats, nextState } = await pushTree(sftp, local, p, { ...body, state, maxFileBytes: config.maxFileBytes })
+          if (!args.dryRun) saveSyncState(local, nextState)
+          let text = `${args.dryRun ? 'WOULD upload' : 'Uploaded'} ${stats.files} file(s) from ${local} → ${p}.`
+          if (stats.skippedUnchanged) text += ` ${stats.skippedUnchanged} unchanged.`
+          if (stats.skippedLarge) text += ` ${stats.skippedLarge} too large (over ${config.maxFileBytes} bytes).`
+          if (stats.staleLocal) text += ` ${stats.staleLocal} local entries gone remotely (kept remotely; use rw_remove to mirror deletions).`
+          if (stats.conflicts.length) {
+            text += `\n⚠ ${stats.conflicts.length} conflict(s), NOT overwritten:`
+            for (const c of stats.conflicts.slice(0, 10)) text += `\n  ${c.path} — ${c.reason}`
+            if (stats.conflicts.length > 10) text += `\n  … and ${stats.conflicts.length - 10} more`
+            text += '\n(use force=true to override)'
+          }
+          return { text }
+        }
+        if (args.async) {
+          const t = tasks.start('push', `push ${p}`, runPush)
+          return { text: `push started in background: taskId=${t.id} (GET /dsh-remote/task?id=${t.id} for progress)` }
+        }
+        return runPush()
+      },
+    }),
+
+    defineTool({
+      name: 'rw_list_dir',
+      description:
+        'List a remote directory (or a single file) via SSH. Path is absolute; if omitted, lists the current remote workspace. Shows type, size, mtime.',
+      parameters: {
+        path: { type: 'string', description: 'Absolute remote path (default: current remote workspace)' },
+      },
+      output: textOut,
+      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')
+        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 fmtMtime = (t) => {
+          if (!t) return '?'
+          const d = new Date(t * 1000)
+          const pad = (n) => String(n).padStart(2, '0')
+          return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}`
+        }
+        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)} ${fmtMtime(a.mtime).padEnd(17)} ${String(e.filename)}`
+          })
+        return { text: lines.length ? lines.join('\n') : '(empty directory)' }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_stat',
+      description:
+        'Show detailed stat of a remote file or directory: type, size, mtime, mode (SFTP attrs). Use to verify a remote path exists or to compare files.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote path' },
+      },
+      output: textOut,
+      async execute(args) {
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p) throw new Error('rw_stat: path is required')
+        const sftp = await pool.sftp()
+        let st
+        try {
+          st = await sftp.stat(p)
+        } catch (err) {
+          throw new Error('rw_stat: not found or unreadable: ' + ((err && err.message) || err))
+        }
+        const type = st.isDirectory && st.isDirectory() ? 'directory' : (st.isSymbolicLink && st.isSymbolicLink() ? 'symlink' : 'file')
+        const lines = [
+          `path: ${p}`,
+          `type: ${type}`,
+          `size: ${st.size} bytes`,
+          `mtime: ${new Date(st.mtime * 1000).toISOString()}`,
+          `mode: ${typeof st.mode === 'number' ? st.mode.toString(8) : '?'}`,
+        ]
+        return { text: lines.join('\n') }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_read_file',
+      description:
+        'Read a text file on the remote host with line numbers. Supports paging with startLine/endLine and an encoding param (utf-8 default, gbk etc). Path is absolute.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote file path' },
+        startLine: { type: 'integer', description: '1-based first line (default 1)' },
+        endLine: { type: 'integer', description: '1-based last line (inclusive)' },
+        maxLines: { type: 'integer', description: 'Max lines (default 2000)' },
+        encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
+      },
+      output: textOut,
+      async execute(args) {
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p) throw new Error('rw_read_file: path is required')
+        const maxLines = Math.min(Math.max(Number(args.maxLines) || 2000, 1), 10000)
+        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 sftp = await pool.sftp()
+        let st
+        try { st = await sftp.stat(p) } catch (err) { throw new Error('rw_read_file: ' + ((err && err.message) || err)) }
+        if (config.maxFileBytes > 0 && st.size > config.maxFileBytes) {
+          throw new Error(`rw_read_file: file is ${st.size} bytes (over ${config.maxFileBytes} cap); use rw_download or rw_exec to read it`)
+        }
+        let buf
         try {
-          sftp = await pool.sftp()
+          buf = await sftp.readFile(p)
         } catch (err) {
-          return { text: 'sftp unavailable: ' + ((err && err.message) || err) }
+          throw new Error('rw_read_file: ' + ((err && err.message) || err))
         }
-        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).`
+        const content = decodeBuf(buf, args.encoding || config.encoding).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 }
       },
     }),
 
     defineTool({
-      name: 'rw_push',
+      name: 'rw_write_file',
+      description:
+        'Write text to a file on the remote host (creating parent directories if needed). Path is absolute. Use this to create or overwrite a remote file directly, instead of round-tripping through a local mirror.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote file path' },
+        content: { type: 'string', required: true, description: 'File content to write (overwrites existing file)' },
+        mkdir: { type: 'boolean', description: 'Create missing parent directories (default true)' },
+        encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
+      },
+      output: okOut,
+      async execute(args) {
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p || p === '/') throw new Error('rw_write_file: a file path is required')
+        const content = String(args.content == null ? '' : args.content)
+        const sftp = await pool.sftp()
+        if (args.mkdir !== false) await mkdirRemoteDirs(sftp, remoteDirname(p))
+        const buf = encodeText(content, args.encoding || config.encoding)
+        await sftp.writeFile(p, buf)
+        const bytes = buf.byteLength
+        audit('write_file', `write ${p} (${bytes}B)`, 0)
+        return { ok: true, bytes, text: `wrote ${bytes} bytes to ${p}` }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_edit',
+      description:
+        'Edit a remote text file by replacing literal text (read-modify-write with an mtime optimistic lock: aborts if the file changed on the remote between read and write). Path is absolute.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote file path' },
+        old: { type: 'string', required: true, description: 'Literal text to replace (must appear exactly once unless count is given)' },
+        new: { type: 'string', required: true, description: 'Replacement text' },
+        count: { type: 'integer', description: 'How many occurrences to replace (default: error if the text appears more than once)' },
+        encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
+      },
+      output: okOut,
+      async execute(args) {
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p || p === '/') throw new Error('rw_edit: a file path is required')
+        const oldS = String(args.old ?? '')
+        const newS = String(args.new ?? '')
+        if (oldS === '') throw new Error('rw_edit: old text must not be empty')
+        const sftp = await pool.sftp()
+        const st0 = await sftp.stat(p)
+        const buf = await sftp.readFile(p)
+        const content = decodeBuf(buf, args.encoding || config.encoding)
+        const count = args.count == null ? 0 : Math.max(Number(args.count) || 1, 1)
+        const idxs = []
+        let from = 0
+        let hit
+        while ((hit = content.indexOf(oldS, from)) !== -1) { idxs.push(hit); from = hit + oldS.length }
+        if (!idxs.length) throw new Error(`rw_edit: old text not found in ${p}`)
+        if (count === 0 && idxs.length > 1) {
+          throw new Error(`rw_edit: "old" appears ${idxs.length} times in ${p} — pass count=<n> to pick how many to replace`)
+        }
+        const n = count === 0 ? 1 : Math.min(count, idxs.length)
+        let out = content
+        for (let i = n - 1; i >= 0; i--) {
+          out = out.slice(0, idxs[i]) + newS + out.slice(idxs[i] + oldS.length)
+        }
+        // Optimistic lock: the remote must not have changed since we read it.
+        const st1 = await sftp.stat(p)
+        if (st1.size !== st0.size || st1.mtime !== st0.mtime) {
+          throw new Error(`rw_edit: ${p} changed on the remote while editing (conflict) — re-read and retry`)
+        }
+        await sftp.writeFile(p, encodeText(out, args.encoding || config.encoding))
+        audit('edit', `edit ${p} (${n} occurrence(s))`, 0)
+        return { ok: true, bytes: Buffer.byteLength(out), text: `edited ${p}: replaced ${n} occurrence(s)` }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_append',
+      description:
+        'Append text to a remote file (creates it when missing). Path is absolute.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote file path' },
+        content: { type: 'string', required: true, description: 'Text to append' },
+        encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
+      },
+      output: okOut,
+      async execute(args) {
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p || p === '/') throw new Error('rw_append: a file path is required')
+        const sftp = await pool.sftp()
+        let existing = ''
+        try { existing = decodeBuf(await sftp.readFile(p), args.encoding || config.encoding) } catch { /* new file */ }
+        const content = existing + String(args.content ?? '')
+        await sftp.writeFile(p, encodeText(content, args.encoding || config.encoding))
+        const bytes = Buffer.byteLength(content)
+        audit('append', `append ${p}`, 0)
+        return { ok: true, bytes, text: `appended to ${p} (now ${bytes} bytes)` }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_mkdir',
       description:
-        'Upload the local mirror of the current remote workspace back to the remote host over SFTP (bounded). Use after editing files in the local mirror so the remote reflects your changes (bidirectional sync).',
+        'Create a remote directory (mkdir -p semantics, all levels). Path is absolute.',
       parameters: {
-        maxFiles: { type: 'integer', description: 'Max files to upload (default 500)' },
-      },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
+        path: { type: 'string', required: true, description: 'Absolute remote directory path' },
       },
+      output: textOut,
       async execute(args) {
-        const p = wsPath()
-        if (!p) throw new Error('rw_push: no remote workspace set — call rw_pick_workspace first')
-        const local = mirrorDirFor(p, config.host, config.username, config.port)
-        if (!existsSync(local)) throw new Error(`rw_push: local mirror does not exist — run rw_sync first (${local})`)
-        const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
-        let sftp
-        try {
-          sftp = await pool.sftp()
-        } catch (err) {
-          return { text: 'sftp unavailable: ' + ((err && err.message) || err) }
-        }
-        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 }
+        const p = normalizeRemotePath(String(args.path || ''))
+        if (!p || p === '/') throw new Error('rw_mkdir: a directory path is required')
+        const sftp = await pool.sftp()
+        await mkdirRemoteDirs(sftp, p)
+        audit('mkdir', `mkdir ${p}`, 0)
+        return { text: `created ${p}` }
       },
     }),
 
     defineTool({
-      name: 'rw_list_dir',
+      name: 'rw_remove',
       description:
-        'List a remote directory (or a single file) via SSH. Path is absolute; if omitted, lists the current remote workspace.',
+        'Delete a remote file (or an empty directory). recursive=true removes a directory tree (bounded). Path is absolute. This is destructive — the agent should confirm intent before calling.',
       parameters: {
-        path: { type: 'string', description: 'Absolute remote path (default: current remote workspace)' },
-      },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
+        path: { type: 'string', required: true, description: 'Absolute remote path to delete' },
+        recursive: { type: 'boolean', description: 'Recursively delete a directory (default false)' },
       },
+      output: okOut,
       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')
-        // 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 p = normalizeRemotePath(String(args.path || ''))
+        if (!p || p === '/') throw new Error('rw_remove: a path is required')
+        const sftp = await pool.sftp()
+        const st = await sftp.stat(p).catch(() => null)
+        if (!st) return { ok: false, text: `not found: ${p}` }
+        if (st.isDirectory && st.isDirectory()) {
+          if (!args.recursive) throw new Error(`rw_remove: ${p} is a directory — pass recursive=true to delete its tree`)
+          const removed = await removeRemoteTree(sftp, p)
+          audit('remove', `remove -r ${p}`, 0)
+          return { ok: true, text: `removed ${removed} entries under ${p}` }
         }
-        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)' }
+        await sftp.unlink(p)
+        audit('remove', `remove ${p}`, 0)
+        return { ok: true, text: `removed ${p}` }
       },
     }),
 
     defineTool({
-      name: 'rw_read_file',
+      name: 'rw_move',
       description:
-        'Read a text file on the remote host with line numbers. Supports paging with startLine/endLine. Path is absolute.', 
+        'Rename or move a remote file/directory (SFTP rename, same filesystem). Paths are absolute.',
       parameters: {
-        path: { type: 'string', required: true, description: 'Absolute remote file path' },
-        startLine: { type: 'integer', description: '1-based first line (default 1)' },
-        endLine: { type: 'integer', description: '1-based last line (inclusive)' },
-        maxLines: { type: 'integer', description: 'Max lines (default 2000)' },
-      },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
+        path: { type: 'string', required: true, description: 'Current absolute remote path' },
+        dest: { type: 'string', required: true, description: 'Destination absolute remote path' },
       },
+      output: textOut,
       async execute(args) {
         const p = normalizeRemotePath(String(args.path || ''))
-        if (!p) throw new Error('rw_read_file: path is required')
-        const maxLines = Math.min(Math.max(Number(args.maxLines) || 2000, 1), 10000)
-        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
-        // 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 }
+        const d = normalizeRemotePath(String(args.dest || ''))
+        if (!p || !d || p === '/') throw new Error('rw_move: both path and dest are required')
+        const sftp = await pool.sftp()
+        await mkdirRemoteDirs(sftp, remoteDirname(d))
+        await sftp.rename(p, d)
+        audit('move', `move ${p} → ${d}`, 0)
+        return { text: `moved ${p} → ${d}` }
       },
     }),
 
     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. Runs in the current remote workspace by default; pass cwd to run elsewhere.',
+        '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. pty=true helps interactive commands (sudo prompts, REPLs); env sets environment variables.',
       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)' },
+        pty: { type: 'boolean', description: 'Allocate a pseudo-terminal (interactive commands, default false)' },
+        env: { type: 'object', description: 'Extra environment variables (string values)' },
       },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
-      },
+      output: textOut,
       async execute(args) {
         const cmd = String(args.command || '')
         if (!cmd) throw new Error('rw_exec: command is required')
         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 }) }
-      },
-    }),
-
-    defineTool({
-      name: 'rw_write_file',
-      description:
-        'Write text to a file on the remote host (creating parent directories if needed). Path is absolute. Use this to create or overwrite a remote file directly, instead of round-tripping through a local mirror.',
-      parameters: {
-        path: { type: 'string', required: true, description: 'Absolute remote file path' },
-        content: { type: 'string', required: true, description: 'File content to write (overwrites existing file)' },
-        mkdir: { type: 'boolean', description: 'Create missing parent directories (default true)' },
-      },
-      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 ? 'written' : 'failed') }],
-      },
-      async execute(args) {
-        const p = normalizeRemotePath(String(args.path || ''))
-        if (!p || p === '/') throw new Error('rw_write_file: a file path is required')
-        const content = String(args.content == null ? '' : args.content)
-        let sftp
         try {
-          sftp = await pool.sftp()
+          const res = await pool.exec(full, { timeoutMs: config.commandTimeoutMs, pty: !!args.pty, env: args.env })
+          audit('exec', cmd, res.code)
+          const parts = []
+          if (res.stdout) parts.push(res.stdout.replace(/\s+$/, ''))
+          if (res.stderr) parts.push('-- stderr --\n' + res.stderr.replace(/\s+$/, ''))
+          if (!parts.length) parts.push('(no output)')
+          let text = parts.join('\n')
+          if (res.signal === 'TIMEOUT') text += `\n[command timed out after ${config.commandTimeoutMs}ms]`
+          else if (res.code !== 0) text += `\n[exit code: ${res.code}]`
+          return { text }
         } catch (err) {
-          throw new Error('rw_write_file: sftp unavailable: ' + ((err && err.message) || err))
+          throw new Error(friendlyMessage(err, { host: config.host, port: config.port }))
         }
-        const mkdir = args.mkdir !== false
-        if (mkdir) {
-          // create each level from the root so mkdir -p semantics survive even
-          // when intermediate privileged-parent dirs don't allow create (best effort)
-          await mkdirRemoteDirs(sftp, p)
-        }
-        const buf = Buffer.from(content, 'utf8')
-        await sftp.writeFile(p, buf)
-        const bytes = Buffer.byteLength(content, 'utf8')
-        return { ok: true, bytes, text: `wrote ${bytes} bytes to ${p}` }
       },
     }),
 
     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.',
+        'Search remote files for a pattern (recursive SFTP walk — works on ANY remote including Windows, honors ignore rules). Returns matching file:line rows; output is capped.',
       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)' },
+        glob: { type: 'string', description: 'Only files whose NAME matches this glob, e.g. *.ts (optional)' },
         ignoreCase: { type: 'boolean', description: 'Case-insensitive search (default true)' },
+        contextLines: { type: 'integer', description: 'Lines of context around each match (default 0)' },
+        maxMatches: { type: 'integer', description: 'Max matches to return (default 500)' },
       },
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
-      },
+      output: textOut,
       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}'"` }
+        let regex
+        try {
+          regex = new RegExp(pattern, args.ignoreCase === false ? '' : 'i')
+        } catch (err) {
+          throw new Error('rw_search: bad pattern: ' + ((err && err.message) || err))
         }
-        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) }) }
+        const sftp = await pool.sftp()
+        const maxMatches = Math.min(Math.max(Number(args.maxMatches) || 500, 1), 2000)
+        const matcher = ignoreMatcher()
+        const { matches, scanned, truncated } = await searchTree(sftp, dir, {
+          regex,
+          glob: args.glob,
+          contextLines: Math.min(Math.max(Number(args.contextLines) || 0, 0), 10),
+          maxMatches,
+          maxScanBytes: Math.min(config.maxFileBytes || 1024 * 1024, 1024 * 1024),
+          isIgnored: (name, isDir) => matcher(name, isDir),
+        })
+        if (!matches.length) return { text: `no matches for /${pattern}/ in ${dir} (${scanned} files scanned)` }
+        let text = matches.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n')
+        text += `\n(${matches.length} match(es), ${scanned} files scanned${truncated ? ', TRUNCATED' : ''})`
+        return { text: truncate(text, config.maxOutputChars) }
       },
     }),
 
     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.',
+        '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. Streams to disk (fastGet).',
       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') }],
-      },
+      output: okOut,
       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))
-        }
+        const sftp = await pool.sftp()
         let local
         if (args.localPath) {
           local = path.resolve(String(args.localPath))
@@ -1350,9 +1571,12 @@ export async function apply(ctx, config) {
           local = path.join(base, rel)
         }
         mkdirSync(path.dirname(local), { recursive: true })
-        const buf = await sftp.readFile(p)
-        writeFileSync(local, buf)
-        const bytes = buf.byteLength
+        const st = await sftp.stat(p).catch(() => null)
+        if (config.maxFileBytes > 0 && st && st.size > config.maxFileBytes) {
+          throw new Error(`rw_download: file is ${st.size} bytes (over ${config.maxFileBytes} cap)`)
+        }
+        await sftp.fastGet(p, local)
+        const bytes = existsSync(local) ? statSync(local).size : 0
         return { ok: true, bytes, text: `downloaded ${bytes} bytes from ${p} → ${local}` }
       },
     }),
@@ -1365,41 +1589,69 @@ export async function apply(ctx, config) {
         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') }],
-      },
+      output: okOut,
       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 sftp = await pool.sftp()
+        await mkdirRemoteDirs(sftp, remoteDirname(rp))
+        const st = statSync(lp)
+        await sftp.fastPut(rp, lp)
+        audit('upload', `upload ${lp} → ${rp}`, 0)
+        return { ok: true, bytes: st.size, text: `uploaded ${st.size} bytes from ${lp} → ${rp}` }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_forward',
+      description:
+        'Manage SSH port forwards. Direction "local" listens on 127.0.0.1:<listenPort> on THIS machine and forwards connections through SSH to <targetHost>:<targetPort> on the remote. Direction "reverse" asks the REMOTE to listen on 127.0.0.1:<listenPort> and pipes connections back to <targetHost>:<targetPort> on this machine. Call with a listenPort to create+start; with remove=true to delete.',
+      parameters: {
+        listenPort: { type: 'integer', required: true, description: 'Port to listen on (local for direction=local, remote for direction=reverse)' },
+        targetHost: { type: 'string', description: 'Forward target host (default 127.0.0.1)' },
+        targetPort: { type: 'integer', description: 'Forward target port (default: same as listenPort)' },
+        direction: { type: 'string', description: 'local (default) or reverse' },
+        autoStart: { type: 'boolean', description: 'Restart this forward automatically on future connects (default false)' },
+        remove: { type: 'boolean', description: 'Remove an existing forward by listenPort (default false)' },
+      },
+      output: textOut,
+      async execute(args) {
+        const port = Number(args.listenPort)
+        if (!port || port < 1 || port > 65535) throw new Error('rw_forward: a valid listenPort is required')
+        const dir = args.direction === 'reverse' ? 'reverse' : 'local'
+        const existing = forwards.list().find((f) => Number(f.listenPort) === port && f.direction === dir)
+        if (args.remove) {
+          if (!existing) return { text: `no forward on port ${port} to remove` }
+          forwards.remove(existing.id)
+          return { text: `removed ${existing.direction} forward on port ${port}` }
         }
-        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}` }
+        if (existing && existing.active) return { text: `already active: ${existing.direction} forward 127.0.0.1:${port} → ${existing.targetHost}:${existing.targetPort}` }
+        const d = existing || forwards.define({
+          direction: dir,
+          listenPort: port,
+          targetHost: args.targetHost || '127.0.0.1',
+          targetPort: Number(args.targetPort) || port,
+          autoStart: !!args.autoStart,
+          machineId: store.currentId,
+        })
+        const r = await forwards.start(d)
+        audit('forward', `${d.direction} forward ${port} → ${d.targetHost}:${d.targetPort}`, r.ok ? 0 : 1)
+        if (!r.ok) throw new Error(r.error)
+        return { text: `${d.direction} forward active: 127.0.0.1:${port} → ${d.targetHost}:${d.targetPort} (id=${d.id})` }
       },
     }),
 
     defineTool({
       name: 'rw_disconnect',
       description:
-        'Close the current SSH connection to the remote host, releasing the persistent pool. Useful to rotate connections or after a long idle.',
+        'Close the current SSH connection to the remote host, releasing the persistent pool (and stopping all active port forwards). Useful to rotate connections or after a long idle.',
       parameters: {},
-      output: {
-        schema: { type: 'object', additionalProperties: false, properties: { ok: { type: 'boolean', required: true }, text: { type: 'string' } } },
-        render: (_a, a) => [{ type: 'text', text: a.text }],
-      },
+      output: okOut,
       async execute() {
         pool.close()
-        return { ok: true, text: 'disconnected' }
+        return { ok: true, text: 'disconnected (forwards stopped)' }
       },
     }),
   ]
@@ -1415,30 +1667,36 @@ export async function apply(ctx, config) {
     text: () => {
       const w = wsPath()
       if (!w || !config.host) return ''
+      const fwd = forwards.list().filter((f) => f.active).map((f) => `${f.direction}:127.0.0.1:${f.listenPort}→${f.targetHost}:${f.targetPort}`)
+      let extra = ''
+      if (fwd.length) extra = `\nActive port forwards: ${fwd.join(', ')}`
       return (
         '## Remote workspace\n' +
         `Current remote workspace: ${config.username}@${config.host}:${w}\n` +
-        '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.'
+        'Use the rw_* tools (rw_list_dir / rw_read_file / rw_write_file / rw_edit / rw_exec / rw_search / rw_sync / rw_push) to inspect and act on files on the remote host. Treat this directory as the working root for this task.' +
+        extra
       )
     },
   })
 
-  // ── slash command: /remote reports status + connection hints ──────────────
+  // ── slash commands ─────────────────────────────────────────────────────────
   const commands = ctx.get('commands')
   if (commands !== undefined) {
     commands.register({
       name: 'remote',
-      description: 'Show the current remote workspace / connection status and how to use remote tools.',
+      description: 'Show the current remote workspace / connection status, active forwards, and how to use remote tools.',
       handler: (invocation) => {
         const s = status()
+        const fwd = s.forwards.filter((f) => f.active)
         return {
           kind: 'success',
           text:
-            `Remote host: ${s.username}@${s.host || '<none>'} (connected: ${s.connected})\n` +
+            `Remote host: ${s.username}@${s.host || '<none>'} (connected: ${s.connected}, source: ${s.activeSource})\n` +
             `Remote workspace: ${s.workspace || '(none)'}\n` +
             `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.` +
+            (fwd.length ? `Active forwards:\n${fwd.map((f) => `  ${f.direction} 127.0.0.1:${f.listenPort} → ${f.targetHost}:${f.targetPort}`).join('\n')}\n` : '') +
+            `\nUse tools: rw_list_dir / rw_read_file / rw_edit / rw_exec / rw_search / rw_forward.` +
             (s.workspace ? `\nCurrently working in ${s.workspace}.` : ''),
         }
       },
@@ -1451,6 +1709,17 @@ export async function apply(ctx, config) {
         return { kind: 'success', text: `forgot host key for ${config.host || '<none>'}:${config.port} — the next connect will re-record it.` }
       },
     })
+    commands.register({
+      name: 'remote-ignore',
+      description: 'Show the mirror ignore rules file location and the current default patterns (gitignore syntax).',
+      handler: () => {
+        return {
+          kind: 'success',
+          text:
+            `Ignore file: ${ignoreFile()}\n(defaults merged with the file; gitignore syntax, '#' comments)\n\nDefault patterns:\n${DEFAULT_IGNORE.map((p) => '  ' + p).join('\n')}`,
+        }
+      },
+    })
   }
 
   // ── JSON endpoints for settings UI ─────────────────────────────────────────
@@ -1462,8 +1731,6 @@ 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) => {
@@ -1482,10 +1749,6 @@ export async function apply(ctx, config) {
     })
 
   // ── 本机目录选择器：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) => {
@@ -1493,14 +1756,13 @@ export async function apply(ctx, config) {
         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 })
+        resolve(p === 'CANCELED' ? { cancelled: true } : (p ? { path: p } : { cancelled: true }))
       })
     })
   const pickLocalNative = async () => {
@@ -1516,9 +1778,18 @@ export async function apply(ctx, config) {
         throw err
       }
     }
+    if (platform === 'win32') {
+      const script =
+        `Add-Type -AssemblyName System.Windows.Forms;` +
+        `$f = New-Object System.Windows.Forms.FolderBrowserDialog;` +
+        `$f.Description = 'Select Workspace Directory';` +
+        `if ($f.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $f.SelectedPath } else { 'CANCELED' }`
+      return runPick('powershell', ['-NoProfile', '-STA', '-Command', script])
+    }
     throw new Error('当前系统不支持自动打开目录选择器，请在输入框直接填本地路径')
   }
 
+  // ── route helpers ─────────────────────────────────────────────────────────
   const routes = [
     {
       kind: 'exact',
@@ -1543,10 +1814,10 @@ export async function apply(ctx, config) {
             privateKeyPath: payload.privateKeyPath,
             workspace: payload.workspace,
           })
-          await pool.exec('echo ok', Math.min(config.commandTimeoutMs, 8000))
+          await pool.exec('echo ok', { timeoutMs: Math.min(config.commandTimeoutMs, 8000) })
           return sendJson(res, 200, { ok: true, ...status() })
         } catch (err) {
-          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+          return sendJson(res, 500, { ok: false, error: friendlyMessage(err, { host: payload && payload.host, port: payload && payload.port }) })
         }
       },
     },
@@ -1555,23 +1826,20 @@ export async function apply(ctx, config) {
       path: '/dsh-remote/ls',
       handler: async (req, res) => {
         try {
-          // 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 })
+          return sendJson(res, 200, { path: out.path, items: out.items })
         } catch (err) {
           return sendJson(res, 500, { error: String((err && err.message) || err) })
         }
       },
     },
     {
-      // Read a remote file over SFTP (live, not the local mirror) for the
-      // sidebar's remote file viewer. Text files come back as UTF-8 content
-      // (CRLF→LF), binary files are reported as binary with size+head bytes
-      // (base64) so the client can sniff the format without loading the
-      // whole file. `maxBytes` caps how much text is returned.
+      // Read a remote file over SFTP (live). Text returns as content (CRLF→LF,
+      // encoding-aware), binary is reported with size+head (base64). A stat
+      // happens first; oversized files are previewed from a streamed head chunk
+      // instead of being fully buffered.
       kind: 'exact',
       path: '/dsh-remote/read',
       handler: async (req, res) => {
@@ -1579,27 +1847,52 @@ export async function apply(ctx, config) {
         try {
           const q = new URL(req.url, 'http://localhost').searchParams
           let p = q.get('path') ? decodeURIComponent(q.get('path')) : ''
+          let encoding = ''
+          let maxBytes = 256 * 1024
           if (req.method === 'POST') {
             const body = JSON.parse((await readBody(req)) || '{}')
             if (!p) p = String(body.path || '')
+            if (body.encoding) encoding = String(body.encoding)
+            if (body.maxBytes) maxBytes = Number(body.maxBytes)
           }
+          if (q.get('maxBytes')) maxBytes = Number(q.get('maxBytes'))
           if (!p) return sendJson(res, 400, { ok: false, error: 'path is required' })
           const target = normalizeRemotePath(p)
-          const maxBytes = Math.min(Math.max(Number(q.get('maxBytes')) || 256 * 1024, 1024), 2 * 1024 * 1024)
+          maxBytes = Math.min(Math.max(Number(maxBytes) || 256 * 1024, 1024), 2 * 1024 * 1024)
           let sftp
           try {
             sftp = await pool.sftp()
           } catch (err) {
             return sendJson(res, 500, { ok: false, error: 'sftp unavailable: ' + ((err && err.message) || err) })
           }
+          let st
+          try { st = await sftp.stat(target) } catch (err) {
+            return sendJson(res, 500, { ok: false, error: 'read failed: ' + ((err && err.message) || err) })
+          }
+          if (st.size > maxBytes) {
+            // Head preview for oversized files: fastGet to a temp file, read the
+            // first maxBytes, delete the temp. Never buffers the whole file.
+            const tmp = path.join(dshBase(), '.dsh-remote-preview-' + process.pid)
+            try {
+              await sftp.fastGet(target, tmp)
+              const { open } = await import('node:fs/promises')
+              const fd = await open(tmp, 'r')
+              const head = Buffer.alloc(Math.min(maxBytes, st.size))
+              await fd.read(head, 0, head.length, 0)
+              await fd.close()
+              try { unlinkSync(tmp) } catch {}
+              const content = decodeBuf(head, encoding || config.encoding).replace(/\r\n/g, '\n')
+              return sendJson(res, 200, { ok: true, binary: false, content, truncated: true, size: st.size })
+            } catch (err) {
+              return sendJson(res, 500, { ok: false, error: 'read failed: ' + ((err && err.message) || err) })
+            }
+          }
           let buf
           try {
             buf = await sftp.readFile(target)
           } catch (err) {
             return sendJson(res, 500, { ok: false, error: 'read failed: ' + ((err && err.message) || err) })
           }
-          // Binary sniff: NUL byte in the first 8KB (or the whole file when
-          // smaller) marks the file binary — matches the sidebar's convention.
           const headN = Math.min(buf.length, 8192)
           let binary = false
           for (let i = 0; i < headN; i++) {
@@ -1608,7 +1901,7 @@ export async function apply(ctx, config) {
           if (binary) {
             return sendJson(res, 200, { ok: true, binary: true, size: buf.length, head: buf.slice(0, Math.min(buf.length, 4096)).toString('base64') })
           }
-          let content = buf.toString('utf8').replace(/\r\n/g, '\n')
+          let content = decodeBuf(buf, encoding || config.encoding).replace(/\r\n/g, '\n')
           const truncated = content.length > maxBytes
           if (truncated) content = content.slice(0, maxBytes) + `\n…[truncated: ${buf.length - maxBytes} more bytes]`
           return sendJson(res, 200, { ok: true, binary: false, content, truncated })
@@ -1617,6 +1910,111 @@ export async function apply(ctx, config) {
         }
       },
     },
+    {
+      // Write a remote file (sidebar editor save). `expectedMtime` is an
+      // optimistic lock: a 409 is returned when the remote changed meanwhile.
+      kind: 'exact',
+      path: '/dsh-remote/write',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const body = JSON.parse((await readBody(req)) || '{}')
+          const p = normalizeRemotePath(String(body.path || ''))
+          if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path is required' })
+          const sftp = await pool.sftp()
+          let st = null
+          try { st = await sftp.stat(p) } catch { /* new file */ }
+          if (body.expectedMtime != null && st && st.mtime !== Number(body.expectedMtime)) {
+            return sendJson(res, 409, { ok: false, error: `远端文件已变化（mtime ${st.mtime} ≠ ${body.expectedMtime}），已放弃保存——请重新读取后再编辑` })
+          }
+          const buf = encodeText(String(body.content ?? ''), body.encoding || config.encoding)
+          if (!st) await mkdirRemoteDirs(sftp, remoteDirname(p))
+          await sftp.writeFile(p, buf)
+          audit('write', `write ${p}`, 0)
+          const st2 = await sftp.stat(p).catch(() => null)
+          return sendJson(res, 200, { ok: true, bytes: buf.byteLength, mtime: st2 ? st2.mtime : Math.floor(Date.now() / 1000) })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
+    {
+      // Generic remote fs ops used by the sidebar context menu + picker:
+      // mkdir / rename / remove (recursive) / write / append.
+      kind: 'exact',
+      path: '/dsh-remote/fs',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const body = JSON.parse((await readBody(req)) || '{}')
+          const op = String(body.op || '')
+          const sftp = await pool.sftp()
+          if (op === 'mkdir') {
+            const p = normalizeRemotePath(String(body.path || ''))
+            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
+            await mkdirRemoteDirs(sftp, p)
+            audit('mkdir', `mkdir ${p}`, 0)
+            return sendJson(res, 200, { ok: true })
+          }
+          if (op === 'rename') {
+            const p = normalizeRemotePath(String(body.path || ''))
+            const d = normalizeRemotePath(String(body.dest || ''))
+            if (!p || !d) return sendJson(res, 400, { ok: false, error: 'path and dest required' })
+            await sftp.rename(p, d)
+            audit('move', `move ${p} → ${d}`, 0)
+            return sendJson(res, 200, { ok: true })
+          }
+          if (op === 'remove') {
+            const p = normalizeRemotePath(String(body.path || ''))
+            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
+            const st = await sftp.stat(p).catch(() => null)
+            if (!st) return sendJson(res, 404, { ok: false, error: 'not found' })
+            if (st.isDirectory && st.isDirectory()) {
+              await removeRemoteTree(sftp, p)
+            } else {
+              await sftp.unlink(p)
+            }
+            audit('remove', `remove ${p}`, 0)
+            return sendJson(res, 200, { ok: true })
+          }
+          if (op === 'write' || op === 'append') {
+            const p = normalizeRemotePath(String(body.path || ''))
+            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
+            let content = ''
+            if (op === 'append') {
+              try { content = decodeBuf(await sftp.readFile(p), body.encoding || config.encoding) } catch { /* new */ }
+            }
+            const buf = encodeText(content + String(body.content ?? ''), body.encoding || config.encoding)
+            if (op === 'write' && !(await sftp.stat(p).catch(() => null))) await mkdirRemoteDirs(sftp, remoteDirname(p))
+            await sftp.writeFile(p, buf)
+            audit(op, `${op} ${p}`, 0)
+            return sendJson(res, 200, { ok: true, bytes: buf.byteLength })
+          }
+          if (op === 'download') {
+            // Download a remote file into the current workspace mirror.
+            const p = normalizeRemotePath(String(body.path || ''))
+            const ws = wsPath()
+            if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path required' })
+            if (!ws) return sendJson(res, 400, { ok: false, error: 'no remote workspace set' })
+            const st = await sftp.stat(p).catch(() => null)
+            if (!st) return sendJson(res, 404, { ok: false, error: 'not found' })
+            if (config.maxFileBytes > 0 && st.size > config.maxFileBytes) {
+              return sendJson(res, 400, { ok: false, error: `file is ${st.size} bytes (over ${config.maxFileBytes} cap)` })
+            }
+            const base = mirrorDirFor(ws, config.host, config.username, config.port)
+            const rel = p.startsWith(ws) ? p.slice(ws.length).replace(/^\/+/, '') : p.slice(1)
+            const local = path.join(base, rel)
+            mkdirSync(path.dirname(local), { recursive: true })
+            await sftp.fastGet(p, local)
+            audit('download', `download ${p}`, 0)
+            return sendJson(res, 200, { ok: true, bytes: st.size, local })
+          }
+          return sendJson(res, 400, { ok: false, error: 'unknown op' })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
     {
       kind: 'exact',
       path: '/dsh-remote/workspace',
@@ -1630,6 +2028,7 @@ export async function apply(ctx, config) {
           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)
+          startAutoPush(local)
           return sendJson(res, 200, { ok: true, workspace: p, localMirror: local, ...status() })
         } catch (err) {
           return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
@@ -1646,12 +2045,11 @@ 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' })
-          // 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)
           persistWorkspace(p)
+          startAutoPush(local)
           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) })
@@ -1664,12 +2062,6 @@ 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 {
-          // 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
@@ -1683,7 +2075,7 @@ export async function apply(ctx, config) {
                 outcome = (typeof p === 'string' && p) ? { path: p } : { cancelled: true }
               }
             } catch (err) {
-              outcome = null // DSH 服务出错 → 落到自持兜底
+              outcome = null
             }
           }
           if (!outcome) {
@@ -1715,30 +2107,63 @@ export async function apply(ctx, config) {
             if (action === 'add' || action === 'update') {
               const host = String(body.host || '').trim()
               if (!host) return sendJson(res, 400, { ok: false, error: 'host required' })
+              const id = body.id || machineId()
+              const i = machineIndex(id)
+              const prev = i >= 0 ? machines[i] : null
+              const credBackend = body.credentialBackend === 'plain' ? 'plain'
+                : (body.encryptPassword ? platformBackend() : (prev && prev.credentialBackend ? prev.credentialBackend : 'plain'))
               const rec = {
-                id: body.id || machineId(),
+                id,
                 name: String(body.name || '').trim() || host,
                 host,
                 port: Number(body.port) || 22,
                 username: String(body.username || '').trim() || 'root',
-                password: body.password || '',
+                password: '',
                 privateKeyPath: String(body.privateKeyPath || '').trim(),
                 passphrase: body.passphrase || '',
                 workspace: String(body.workspace || '').trim(),
+                hostKeyMode: body.hostKeyMode || '',
+                useAgent: !!body.useAgent,
+                keyboardInteractive: !!body.keyboardInteractive,
+                proxy: body.proxy && body.proxy.host ? {
+                  host: String(body.proxy.host),
+                  port: Number(body.proxy.port) || 22,
+                  username: String(body.proxy.username || '').trim(),
+                  password: String(body.proxy.password || ''),
+                  privateKeyPath: String(body.proxy.privateKeyPath || '').trim(),
+                } : undefined,
+                credentialBackend: credBackend,
+                recentWorkspaces: prev && prev.recentWorkspaces ? prev.recentWorkspaces : [],
+                lastConnectedAt: prev && prev.lastConnectedAt ? prev.lastConnectedAt : null,
+                latencyMs: prev && prev.latencyMs ? prev.latencyMs : null,
+              }
+              if (body.password) {
+                if (credBackend !== 'plain') {
+                  await saveSecret(id, String(body.password), secretsDir())
+                  rec.password = ''
+                } else {
+                  rec.password = String(body.password)
+                }
+              } else if (prev && prev.password) {
+                rec.password = prev.password
               }
-              const i = machineIndex(rec.id)
               if (i >= 0) machines[i] = rec; else machines.push(rec)
-              if (!store.currentId) { store.currentId = rec.id }
+              if (!store.currentId) store.currentId = id
               saveMachines(machines, store.currentId)
-              if (store.currentId === rec.id) applyMachine(config, rec)
+              if (store.currentId === id) await applyActiveMachine()
               return sendJson(res, 200, { ok: true, machine: sanitizeMachine(rec), machines: machines.map(sanitizeMachine), currentId: store.currentId })
             }
             if (action === 'delete') {
               const i = machineIndex(String(body.id || ''))
               if (i < 0) return sendJson(res, 404, { ok: false, error: 'machine not found' })
+              const m = machines[i]
+              if (m.credentialBackend && m.credentialBackend !== 'plain') {
+                await deleteSecret(m.id, secretsDir()).catch(() => {})
+              }
               machines.splice(i, 1)
               if (store.currentId === body.id) store.currentId = machines[0] ? machines[0].id : null
               saveMachines(machines, store.currentId)
+              if (store.currentId) await applyActiveMachine()
               return sendJson(res, 200, { ok: true, machines: machines.map(sanitizeMachine), currentId: store.currentId })
             }
             return sendJson(res, 400, { ok: false, error: 'unknown action' })
@@ -1764,16 +2189,30 @@ export async function apply(ctx, config) {
             password: String(body.password || ''),
             privateKeyPath: String(body.privateKeyPath || config.privateKeyPath),
             passphrase: String(body.passphrase || ''),
+            proxy: body.proxy && body.proxy.host ? {
+              host: String(body.proxy.host),
+              port: Number(body.proxy.port) || 22,
+              username: String(body.proxy.username || ''),
+              password: String(body.proxy.password || ''),
+              privateKeyPath: String(body.proxy.privateKeyPath || ''),
+            } : undefined,
             connectTimeoutMs: Math.min(Math.max(Number(body.connectTimeoutMs) || config.connectTimeoutMs, 2000), 30000),
             commandTimeoutMs: 10000,
           })
           const started = Date.now()
           await probe.connect()
-          await probe.exec('true', 10000)
+          await probe.exec('true', { timeoutMs: 10000 })
           probe.close()
-          return sendJson(res, 200, { ok: true, host: probe.config.host, user: probe.config.username, latencyMs: Date.now() - started })
+          const latencyMs = Date.now() - started
+          const mi = machines.findIndex((m) => m.host === probe.config.host && m.username === probe.config.username && Number(m.port) === probe.config.port)
+          if (mi >= 0) {
+            machines[mi].lastConnectedAt = new Date().toISOString()
+            machines[mi].latencyMs = latencyMs
+            saveMachines(machines, store.currentId)
+          }
+          return sendJson(res, 200, { ok: true, host: probe.config.host, user: probe.config.username, latencyMs, lastConnectedAt: new Date().toISOString() })
         } catch (err) {
-          return sendJson(res, 200, { ok: false, error: String((err && err.message) || err) })
+          return sendJson(res, 200, { ok: false, error: friendlyMessage(err, { host: body && body.host, port: body && body.port }) })
         }
       },
     },
@@ -1784,7 +2223,7 @@ export async function apply(ctx, config) {
         if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
         try {
           const body = JSON.parse((await readBody(req)) || '{}')
-          const okSet = setCurrent(String(body.id || ''))
+          const okSet = await setCurrent(String(body.id || ''))
           if (!okSet) return sendJson(res, 404, { ok: false, error: 'machine not found' })
           return sendJson(res, 200, { ok: true, ...status() })
         } catch (err) {
@@ -1797,15 +2236,193 @@ export async function apply(ctx, config) {
       path: '/dsh-remote/forget-key',
       handler: async (req, res) => {
         if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
-        // 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() })
       },
     },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/forwards',
+      handler: async (req, res) => {
+        if (req.method === 'GET') return sendJson(res, 200, { forwards: forwards.list() })
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const body = JSON.parse((await readBody(req)) || '{}')
+          const action = String(body.action || '')
+          if (action === 'define') {
+            const d = forwards.define({
+              direction: body.direction === 'reverse' ? 'reverse' : 'local',
+              listenPort: Number(body.listenPort),
+              targetHost: body.targetHost || '127.0.0.1',
+              targetPort: Number(body.targetPort) || Number(body.listenPort),
+              autoStart: !!body.autoStart,
+              machineId: store.currentId,
+            })
+            return sendJson(res, 200, { ok: true, forward: d, forwards: forwards.list() })
+          }
+          if (action === 'start' || action === 'stop') {
+            const d = forwards.list().find((f) => f.id === body.id)
+            if (!d) return sendJson(res, 404, { ok: false, error: 'forward not found' })
+            if (action === 'start') {
+              const r = await forwards.start(d)
+              if (!r.ok) return sendJson(res, 500, { ok: false, error: r.error })
+            } else {
+              forwards.stop(d.id)
+            }
+            return sendJson(res, 200, { ok: true, forwards: forwards.list() })
+          }
+          if (action === 'remove') {
+            forwards.remove(String(body.id || ''))
+            return sendJson(res, 200, { ok: true, forwards: forwards.list() })
+          }
+          return sendJson(res, 400, { ok: false, error: 'unknown action' })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/task',
+      handler: async (req, res) => {
+        if (req.method === 'GET') {
+          const q = new URL(req.url, 'http://localhost').searchParams
+          const id = q.get('id') || ''
+          const t = tasks.get(id)
+          if (!t) return sendJson(res, 404, { ok: false, error: 'task not found' })
+          return sendJson(res, 200, { ok: true, task: t })
+        }
+        if (req.method === 'POST') {
+          try {
+            const body = JSON.parse((await readBody(req)) || '{}')
+            const id = String(body.id || '')
+            if (body.action === 'cancel') {
+              const ok = tasks.cancel(id)
+              return sendJson(res, 200, { ok, task: tasks.get(id) })
+            }
+            return sendJson(res, 400, { ok: false, error: 'unknown action' })
+          } catch (err) {
+            return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+          }
+        }
+        return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/tasks',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        return sendJson(res, 200, { ok: true, tasks: tasks.list() })
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/audit',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        const q = new URL(req.url, 'http://localhost').searchParams
+        return sendJson(res, 200, { ok: true, auditEnabled: !!config.auditLog, file: auditFile(), lines: readAudit(q.get('limit')) })
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/ssh-config',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const text = readSshConfigText()
+          return sendJson(res, 200, { ok: true, file: sshConfigPath(), present: !!text, entries: importableEntries(text) })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/home',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const out = await pool.exec('echo ~', { timeoutMs: Math.min(config.commandTimeoutMs, 5000) })
+          const home = String(out.stdout || '').replace(/\s+/g, '').trim()
+          if (!home) return sendJson(res, 200, { ok: true, home: null, hint: 'Windows 远程暂不支持 ~ 解析，请直接输入绝对路径' })
+          return sendJson(res, 200, { ok: true, home })
+        } catch (err) {
+          return sendJson(res, 200, { ok: true, home: null, error: String((err && err.message) || err) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/update-check',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        const current = readVersion()
+        const latest = await fetchLatestVersion()
+        if (latest === null) return sendJson(res, 200, { ok: false, current, error: '无法连接 npm registry' })
+        return sendJson(res, 200, {
+          ok: true,
+          current,
+          latest,
+          updateAvailable: gtVersion(latest, current),
+          updateMode: readUpdateMode() || config.updateMode,
+          updatedMarker: existsSync(path.join(selfDir(), '.dsh-remote-updated')),
+        })
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/update-apply',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const body = JSON.parse((await readBody(req)) || '{}')
+          const target = String(body.version || '')
+          if (!target) return sendJson(res, 400, { ok: false, error: 'version is required' })
+          const result = await applyUpdate(target)
+          return sendJson(res, 200, { ok: true, from: readVersion(), ...result })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/update-mode',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        try {
+          const body = JSON.parse((await readBody(req)) || '{}')
+          const mode = String(body.mode || '')
+          if (!['manual', 'auto', 'off'].includes(mode)) return sendJson(res, 400, { ok: false, error: 'mode must be manual | auto | off' })
+          if (!persistUpdateMode(mode)) return sendJson(res, 500, { ok: false, error: 'cannot persist mode' })
+          return sendJson(res, 200, { ok: true, mode })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
   ]
 
   const disposers = routes.map((r) => webServer.register(r))
   ctx.effect(() => () => disposers.forEach((d) => d && d()), 'dsh-remote.routes')
-}
+
+  // ── auto-update: check on load + on an interval; apply silently ───────────
+  // Failures are swallowed (never break the plugin). The persisted override
+  // (settings UI) wins over the profile-config default.
+  const effectiveUpdateMode = readUpdateMode() || config.updateMode
+  if (effectiveUpdateMode === 'auto') {
+    const currentVersion = readVersion()
+    const checkAndApply = async () => {
+      const latest = await fetchLatestVersion()
+      if (latest && gtVersion(latest, currentVersion)) {
+        try { await applyUpdate(latest) } catch {}
+      }
+    }
+    void checkAndApply()
+    const updateTimer = setInterval(checkAndApply, Math.max(config.updateCheckIntervalMs, 60000))
+    if (typeof updateTimer.unref === 'function') updateTimer.unref()
+    ctx.effect(() => () => clearInterval(updateTimer), 'dsh-remote.update-timer')
+  }
+}