dsh-remote 0.8.37 → 0.8.38

package/lib/index.js

@@ -53,7 +53,13 @@ import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeM
 import { registerHttpTransports } from './http-transport.js'
 import { SshPool } from './pool.js'
 import { createFsRoutes } from './routes-fs.js'
+import { createBackupRoutes } from './routes-backup.js'
 import { listDirStructured, removeRemoteTree } from './remote-fs.js'
+import {
+  createBackup, listBackups, restoreBackup, describeCreate, localBackupDirFor, resolveRemoteHome,
+  pullBackup, pushBackup, deleteBackup, listLocalBackups,
+} from './backup.js'
+import { parseExcludes, resolveBackupDir, isSafeArchiveName, formatBytes, DEFAULT_MAX_TRANSFER_BYTES } from './archive.js'
 
 export const name = 'dsh-remote'
 
@@ -192,6 +198,19 @@ export const Config = z.object({
   /** npm registry to install from. Empty uses the remote's own npm config, which
    *  is what an internal mirror needs to stay in effect. */
   webInstallRegistry: z.string().default(''),
+  /** Directory that workspace backups are written to on the REMOTE host. Empty
+   *  means `$HOME/.dsh-remote/backups`, resolved on the remote (so a remote
+   *  $HOME is never guessed from the local machine). */
+  backupDir: z.string().default(''),
+  /** Exclude patterns applied to backups by default (gitignore-ish, one per
+   *  line). Deliberately EMPTY: a backup that silently omits directories is how
+   *  a "restore" turns into silent data loss. Add patterns here (or per call)
+   *  when you want a smaller archive. */
+  backupExcludes: z.array(z.string()).default([]),
+  /** Cap (bytes) on copying an archive between the remote and this machine.
+   *  The archive on the remote is never truncated — this only bounds the
+   *  optional cross-machine transfer. 0 = unlimited. */
+  maxBackupTransferBytes: z.number().step(1).min(0).default(DEFAULT_MAX_TRANSFER_BYTES),
 })
 
 // ── shell / path helpers (pure implementations in lib/paths.js) ───────────
@@ -1278,6 +1297,20 @@ export async function apply(ctx, config) {
     return normalizeRemotePath(b.ws ? joinRemoteRel(b.ws, rel.replace(/\\/g, '/')) : rel)
   }
 
+  // ── backup helpers (shared by the tools and the /dsh-remote/backup routes) ─
+  /** The remote directory backups land in: the configured override, else
+   *  `$HOME/.dsh-remote/backups` resolved ON THE REMOTE (never guessed from the
+   *  local machine, whose home has nothing to do with the remote one). */
+  const backupDirForBinding = async (b) => {
+    const override = String(config.backupDir || '').trim()
+    if (override) return resolveBackupDir('', override)
+    if (!b || !b.pool) return ''
+    const home = await resolveRemoteHome(b.pool)
+    return resolveBackupDir(home, '')
+  }
+  /** Local directory holding archives pulled from one machine. */
+  const localBackupRootFor = (b) => localBackupDirFor(mirrorRootFor(b.host, b.username, b.port))
+
   // ── tools ─────────────────────────────────────────────────────────────────
 
   const textOut = {
@@ -1345,84 +1378,160 @@ 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. 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. With useSshConfig=true, `host` is an ALIAS from ~/.ssh/config and every value (HostName/user/port/IdentityFile/ProxyJump) is read from that file at connect time.',
+        'Connect SSH to a remote host for remote workspace work. Two ways (issue #48): (1) pass machineId to connect with a machine ALREADY SAVED in the registry (list them with rw_machines) — every stored setting applies: password/keychain password, privateKeyPath + passphrase, useAgent, keyboardInteractive, proxy, hostKeyMode, and ~/.ssh/config aliases; or (2) pass host plus any of username/port/password/privateKeyPath/passphrase/useAgent/keyboardInteractive/hostKeyMode/name. 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. With useSshConfig=true, `host` is an ALIAS from ~/.ssh/config and every value (HostName/user/port/IdentityFile/ProxyJump) is read from that file at connect time. A failed connection is reported as an error message — it never takes the plugin down.',
       parameters: {
-        host: { type: 'string', required: true, description: 'Remote host IP or hostname (or a ~/.ssh/config alias with useSshConfig=true)' },
+        host: { type: 'string', description: 'Remote host IP or hostname (or a ~/.ssh/config alias with useSshConfig=true). Required unless machineId is given.' },
+        machineId: { type: 'string', description: 'Connect with a saved machine from the registry (see rw_machines): all its stored settings apply and it becomes the current machine. host/other fields are not needed.' },
         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' },
+        passphrase: { type: 'string', description: 'Passphrase for an ENCRYPTED private key — required when the key is passphrase-protected, otherwise ssh2 cannot parse it (issue #48)' },
+        useAgent: { type: 'boolean', description: 'Authenticate via the local SSH agent (SSH_AUTH_SOCK) instead of password/key' },
+        keyboardInteractive: { type: 'boolean', description: 'Enable keyboard-interactive auth (OTP/动态码 prompts answered with the configured password)' },
+        hostKeyMode: { type: 'string', description: 'Host-key policy for this machine: ask | strict | off (default from config)' },
+        name: { type: 'string', description: 'Display name for a newly saved machine (default: the host)' },
         useSshConfig: { type: 'boolean', description: 'Treat `host` as a ~/.ssh/config Host alias; resolve host/user/port/key/proxy from that file (issue #38)' },
         save: { type: 'boolean', description: 'Save this machine to the registry and make it current (default true)' },
       },
       output: textOut,
       async execute(args) {
-        const host = String(args.host || '').trim()
-        if (!host) throw new Error('rw_connect: host is required')
-        const useSshConfig = !!args.useSshConfig
-        const user = args.username || config.username || 'root'
-        const port = Number(args.port) || undefined
-        const rec = {
-          host,
-          port: port || 22,
-          username: user,
-          password: args.password !== undefined ? String(args.password) : '',
-          privateKeyPath: args.privateKeyPath || '',
-        }
-        if (useSshConfig) rec.useSshConfig = true
-        // An alias connection must dial the RESOLVED identity (~/.ssh/config),
-        // while the registry keeps the alias itself.
-        const eff = useSshConfig ? withSshConfig(rec) : rec
-        const effUser = eff.username || user
-        const effPort = Number(eff.port) || port || 22
-        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, useSshConfig, 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)
-          }
+        const mid = String(args.machineId || '').trim()
+        if (mid) {
+          // Connect with an ALREADY SAVED machine (issue #48): the registry
+          // record carries everything the tool schema could not re-supply —
+          // keychain-backed passwords, stored passphrases, proxies, aliases.
+          const i = machineIndex(mid)
+          if (i < 0) throw new Error(`rw_connect: no saved machine "${mid}" — list saved machines with rw_machines`)
+          store.currentId = machines[i].id
           ephemeral = null
+          saveMachines(machines, store.currentId)
           // rw_connect means "connect now": force a fresh dial even for an
-          // identical target (setTarget alone would reuse a possibly half-open
-          // cached client — same reconnect-probe reasoning as /connect).
+          // identical target (same reconnect-probe reasoning as below).
           pool.invalidate()
           await applyActiveMachine()
         } else {
-          ephemeral = { id: machineId(), name: host, ...rec }
-          // rw_connect means "connect now": force a fresh dial even for an
-          // identical target (setTarget alone would reuse a possibly half-open
-          // cached client — same reconnect-probe reasoning as /connect).
-          pool.invalidate()
-          pool.setTarget({
-            host: eff.host, port: effPort, username: effUser,
-            password: rec.password, privateKeyPath: eff.privateKeyPath || '',
-            proxy: eff.proxy,
-            workspace: config.workspace,
-          })
+          const host = String(args.host || '').trim()
+          if (!host) throw new Error('rw_connect: host is required — or pass machineId to connect with a saved machine (list them with rw_machines)')
+          const useSshConfig = !!args.useSshConfig
+          const user = args.username || config.username || 'root'
+          const port = Number(args.port) || undefined
+          const rec = {
+            host,
+            port: port || 22,
+            username: user,
+            password: args.password !== undefined ? String(args.password) : '',
+            privateKeyPath: args.privateKeyPath || '',
+          }
+          // Carry ONLY the fields the caller actually passed: the upsert below
+          // merges rec over the stored record, and an always-present default
+          // would clobber stored values (e.g. wiping a saved passphrase).
+          if (args.passphrase !== undefined) rec.passphrase = String(args.passphrase)
+          if (args.useAgent !== undefined) rec.useAgent = !!args.useAgent
+          if (args.keyboardInteractive !== undefined) rec.keyboardInteractive = !!args.keyboardInteractive
+          if (args.hostKeyMode) rec.hostKeyMode = String(args.hostKeyMode)
+          if (args.name) rec.name = String(args.name)
+          if (useSshConfig) rec.useSshConfig = true
+          // An alias connection must dial the RESOLVED identity (~/.ssh/config),
+          // while the registry keeps the alias itself.
+          const eff = useSshConfig ? withSshConfig(rec) : rec
+          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, useSshConfig, id: machines[i].id,
+                // Secrets not re-supplied keep their stored values.
+                password: rec.password || machines[i].password || '',
+                passphrase: rec.passphrase !== undefined ? rec.passphrase : (machines[i].passphrase || ''),
+              }
+              store.currentId = machines[i].id
+              saveMachines(machines, store.currentId)
+            } else {
+              const id = machineId()
+              machines.push({ id, name: rec.name || host, ...rec })
+              store.currentId = id
+              saveMachines(machines, store.currentId)
+            }
+            ephemeral = null
+            // rw_connect means "connect now": force a fresh dial even for an
+            // identical target (setTarget alone would reuse a possibly half-open
+            // cached client — same reconnect-probe reasoning as /connect).
+            pool.invalidate()
+            await applyActiveMachine()
+          } else {
+            ephemeral = { id: machineId(), name: rec.name || host, ...rec }
+            // rw_connect means "connect now": force a fresh dial even for an
+            // identical target (setTarget alone would reuse a possibly half-open
+            // cached client — same reconnect-probe reasoning as /connect).
+            pool.invalidate()
+            pool.setTarget({
+              host: eff.host, port: Number(eff.port) || port || 22, username: eff.username || user,
+              password: rec.password, privateKeyPath: eff.privateKeyPath || '',
+              // Explicit (non-undefined) values so a stale passphrase/agent flag
+              // from a previous target cannot leak into this connection.
+              passphrase: eff.passphrase || '',
+              useAgent: !!rec.useAgent,
+              keyboardInteractive: !!rec.keyboardInteractive,
+              hostKeyMode: rec.hostKeyMode || config.hostKeyMode,
+              proxy: eff.proxy,
+              workspace: config.workspace,
+            })
+          }
         }
+        // Shared probe tail: after either path the shared config holds the
+        // effective dial identity (applyActiveMachine / setTarget wrote it).
+        const effHost = config.host
+        const effUser = config.username
+        const effPort = Number(config.port) || 22
         try {
           const res = await pool.exec('echo ok', { timeoutMs: 8000 })
           if (res.code !== 0 && !res.stdout) {
-            audit('connect', `connect ${effUser}@${eff.host}:${effPort}`, res.code)
+            audit('connect', `connect ${effUser}@${effHost}:${effPort}`, res.code)
             return { text: 'connect failed: ' + (res.stderr || 'exit ' + res.code) }
           }
-          audit('connect', `connect ${effUser}@${eff.host}:${effPort}`, 0)
-          const via = useSshConfig ? `\n(ssh-config alias "${host}" → ${effUser}@${eff.host}:${effPort}` + (eff.sshConfigWarnings && eff.sshConfigWarnings.length ? `; ${eff.sshConfigWarnings.join(' ')}` : '') + ')' : ''
-          return { text: `Connected to ${eff.host} as ${config.username}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
+          audit('connect', `connect ${effUser}@${effHost}:${effPort}`, 0)
+          const active = activeMachine()
+          const via = active && active.sshAlias
+            ? `\n(ssh-config alias "${active.sshAlias}" → ${effUser}@${effHost}:${effPort}` + (active.sshConfigWarnings && active.sshConfigWarnings.length ? `; ${active.sshConfigWarnings.join(' ')}` : '') + ')'
+            : ''
+          return { text: `Connected to ${effHost} as ${effUser}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
         } catch (err) {
-          throw new Error(friendlyMessage(err, { host: eff.host, port: effPort }))
+          throw new Error(friendlyMessage(err, { host: effHost, port: effPort }))
         }
       },
     }),
 
+    defineTool({
+      name: 'rw_machines',
+      description:
+        'List the machines saved in the registry, secrets stripped: id, name, host/port/username, auth method flags (password / key + whether a passphrase is set / agent / keyboard-interactive), ssh-config alias resolution, workspace, and which one is current. Then pass rw_connect(machineId=<id>) to connect with a machine\'s full stored settings — the fix for "the agent cannot retype the whole config" (issue #48).',
+      parameters: {},
+      output: textOut,
+      async execute() {
+        if (!machines.length) {
+          return { text: 'No saved machines yet — add one in Settings → 远程工作区, or connect with rw_connect(host=..., save defaults to true).' }
+        }
+        const lines = machines.map((m) => {
+          const cur = store.currentId === m.id ? '  [CURRENT]' : ''
+          const auth = []
+          if (m.password || (m.credentialBackend && m.credentialBackend !== 'plain')) auth.push('password')
+          if (m.privateKeyPath) auth.push(`key:${m.privateKeyPath}${m.passphrase ? ' (passphrase set)' : ''}`)
+          if (m.useAgent) auth.push('agent')
+          if (m.keyboardInteractive) auth.push('keyboard-interactive')
+          let via = ''
+          if (m.useSshConfig) {
+            const eff = withSshConfig(m)
+            via = `  alias→${eff.username || ''}@${eff.host}:${Number(eff.port) || 22}`
+          }
+          const ws = m.workspace ? `  workspace=${m.workspace}` : ''
+          return `- ${m.id}  "${m.name || m.host}"  ${m.username || ''}@${m.host}:${Number(m.port) || 22}${via}${cur}\n    auth: ${auth.join(' + ') || 'NONE (connect will fail — add credentials)'}${ws}`
+        })
+        return { text: lines.join('\n') + '\n\nconnect with rw_connect(machineId=<id>) to reuse a machine\'s full stored settings.' }
+      },
+    }),
+
     defineTool({
       name: 'rw_pick_workspace',
       description:
@@ -2149,6 +2258,159 @@ export async function apply(ctx, config) {
         return { ok: true, text: `disconnected ${b.username}@${b.host}:${b.port} for this session` }
       },
     }),
+
+    defineTool({
+      name: 'rw_backup',
+      description:
+        'Create a compressed (.tar.gz) backup of the remote workspace (or a subdirectory of it) on the remote host, with an optional copy pulled to this machine. Archives are written under $HOME/.dsh-remote/backups (config backupDir) with a sidecar .meta.json recording the workspace, entry count and sha256. Add exclude patterns when you want a smaller archive — by default EVERYTHING is archived, because silently omitting files is how a restore becomes silent data loss. Use rw_backup_list to see what exists and rw_restore to restore one.',
+      parameters: {
+        path: { type: 'string', description: 'Directory to back up (default and normally: the current remote workspace). Must be the workspace or a subdirectory of it.' },
+        label: { type: 'string', description: 'Optional tag embedded in the archive filename (e.g. "before-refactor").' },
+        excludes: { type: 'string', description: 'Comma- or newline-separated extra exclude patterns (gitignore-ish: node_modules, /build/, *.log). Relative paths inside the workspace.' },
+        dest: { type: 'string', description: 'Where the archive ends up: remote (default), local (pulled here; the remote staging copy is removed), or both.' },
+      },
+      output: textOut,
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_backup')
+        const dir = resolveRemoteArg(b, args.path || '')
+        if (!dir || dir === '/') throw new Error('rw_backup: a directory to back up is required')
+        const root = normalizeRemotePath(b.ws || '')
+        if (root && dir !== root && !dir.startsWith(root.replace(/\/+$/, '') + '/')) {
+          throw new Error(`rw_backup: ${dir} is outside this session's remote workspace (${root}) — backups are limited to the workspace tree`)
+        }
+        // Config defaults first, then this call's own patterns, so a caller can
+        // extend the profile's excludes without restating them.
+        const parsed = parseExcludes([
+          ...(Array.isArray(config.backupExcludes) ? config.backupExcludes : []),
+          ...String(args.excludes || '').split(/[\r\n,]+/),
+        ])
+        const backupDir = await backupDirForBinding(b)
+        if (!backupDir) throw new Error('rw_backup: cannot determine the remote $HOME — set the backupDir config option')
+        const dest = ['remote', 'local', 'both'].includes(String(args.dest)) ? String(args.dest) : 'remote'
+        const result = await createBackup(b.pool, {
+          dir,
+          backupDir,
+          label: args.label ? String(args.label) : '',
+          excludes: parsed.patterns,
+          meta: { host: b.host, username: b.username, port: b.port, label: args.label ? String(args.label) : '' },
+        })
+        if (!result.ok) {
+          audit('backup', `backup ${dir} failed: ${result.error}`, 1, b)
+          throw new Error('rw_backup: ' + result.error)
+        }
+        audit('backup', `backup ${dir} → ${result.archive}`, 0, b)
+        const lines = [describeCreate(result, { dest })]
+        lines.push(`remote archive: ${result.archive}`)
+        if (result.meta && result.meta.excludes && result.meta.excludes.length) lines.push(`excludes: ${result.meta.excludes.join(', ')}`)
+        if (parsed.dropped.length) lines.push(`ignored (no usable pattern): ${parsed.dropped.join(', ')}`)
+        if (dest === 'local' || dest === 'both') {
+          const pulled = await pullBackup(b.pool, {
+            archive: result.archive,
+            localDir: localBackupDirFor(mirrorRootFor(b.host, b.username, b.port)),
+            maxTransferBytes: Number(config.maxBackupTransferBytes) || 0,
+          })
+          if (pulled.ok) {
+            lines.push(`local copy: ${pulled.localPath}`)
+            if (dest === 'local') {
+              const del = await deleteBackup(b.pool, { archive: result.archive })
+              lines.push(del.ok ? 'remote staging copy removed (dest=local)' : `could NOT remove the remote copy: ${del.error || 'unknown error'}`)
+            }
+          } else {
+            lines.push(`local copy FAILED: ${pulled.error}`)
+          }
+        }
+        return { text: lines.join('\n') }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_backup_list',
+      description:
+        "List the compressed backups of this session's remote workspace: name, size, entry count, and when it was taken. Shows both the archives stored on the remote host and any pulled into the local machine. Use the exact `name` with rw_restore.",
+      parameters: {
+        path: { type: 'string', description: "Directory whose backups to list (default: the workspace). Backups are named by workspace, so passing a subdirectory lists that subdirectory's backups." },
+      },
+      output: textOut,
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_backup_list')
+        const backupDir = await backupDirForBinding(b)
+        const remote = backupDir
+          ? await listBackups(b.pool, { dir: backupDir })
+          : { exists: false, dir: '', entries: [], error: '' }
+        const localDir = localBackupDirFor(mirrorRootFor(b.host, b.username, b.port))
+        const local = listLocalBackups(localDir)
+        const fmt = (e) => {
+          const bits = [e.name, formatBytes(e.bytes)]
+          if (e.members != null) bits.push(`${e.members} entries`)
+          if (e.createdAt || e.mtime) bits.push(e.createdAt || e.mtime)
+          if (!e.hasMeta) bits.push('NO SIDECAR (metadata unknown)')
+          return '  ' + bits.join('  |  ')
+        }
+        const lines = []
+        if (!backupDir) {
+          lines.push('(cannot resolve the remote backup directory — set the backupDir config option)')
+        } else if (remote.error) {
+          lines.push(`remote listing failed: ${remote.error}`)
+        } else if (!remote.entries.length) {
+          lines.push(`no backups yet in ${backupDir} (create one with rw_backup)`)
+        } else {
+          lines.push(`${remote.entries.length} remote backup(s) in ${backupDir}:`)
+          lines.push(...remote.entries.map(fmt))
+        }
+        if (local.entries.length) {
+          lines.push('', `${local.entries.length} local copy(ies) in ${localDir}:`)
+          lines.push(...local.entries.map(fmt))
+        }
+        lines.push('', 'restore one with rw_restore(file=<name>).')
+        return { text: lines.join('\n') }
+      },
+    }),
+
+    defineTool({
+      name: 'rw_restore',
+      description:
+        'Restore a workspace from one of its compressed backups (list them with rw_backup_list). The archive is verified BEFORE anything is written; a corrupt or truncated archive is refused and the target is left untouched. mode=replace (default) swaps the target for the archive contents and removes files not present in the archive; mode=merge extracts over the existing tree and deletes nothing. Prefer replace for "give me back exactly the state I archived"; use merge only when the archive is known to be a partial overlay.',
+      parameters: {
+        file: { type: 'string', required: true, description: 'Backup archive filename from rw_backup_list (e.g. proj-abc-2026-10-08T11-22-33.tar.gz).' },
+        target: { type: 'string', description: 'Directory to restore into (default: the current remote workspace). Usually left unset.' },
+        mode: { type: 'string', description: 'replace (default) or merge.' },
+        where: { type: 'string', description: 'Which copy to restore from: remote (default) or local (a pulled copy; it is uploaded back first).' },
+      },
+      output: textOut,
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_restore')
+        const file = String(args.file || '').trim()
+        if (!file) throw new Error('rw_restore: file is required (list them with rw_backup_list)')
+        if (!isSafeArchiveName(file)) throw new Error(`rw_restore: ${file} is not a valid backup filename (expected a plain *.tar.gz basename)`)
+        const target = args.target ? resolveRemoteArg(b, args.target) : (b.ws || '')
+        if (!target || target === '/') throw new Error('rw_restore: no restore target — pick a remote workspace first')
+        const root = normalizeRemotePath(b.ws || '')
+        if (root && target !== root && !target.startsWith(root.replace(/\/+$/, '') + '/')) {
+          throw new Error(`rw_restore: refusing to restore into ${target} — it is outside this session's remote workspace (${root})`)
+        }
+        const mode = args.mode === 'merge' ? 'merge' : 'replace'
+        const backupDir = await backupDirForBinding(b)
+        if (!backupDir) throw new Error('rw_restore: cannot determine the remote backup directory — set the backupDir config option')
+        const where = args.where === 'local' ? 'local' : 'remote'
+        let archive = `${backupDir.replace(/\/+$/, '')}/${file}`
+        if (where === 'local') {
+          const localDir = localBackupDirFor(mirrorRootFor(b.host, b.username, b.port))
+          const up = await pushBackup(b.pool, {
+            localPath: path.join(localDir, file),
+            remoteDir: backupDir,
+            maxTransferBytes: Number(config.maxBackupTransferBytes) || 0,
+          })
+          if (!up.ok) throw new Error('rw_restore: could not upload the local copy — ' + up.error)
+          archive = up.remotePath
+        }
+        const r = await restoreBackup(b.pool, { archive, target, mode })
+        audit('restore', `${mode} restore ${file} → ${target}`, r.ok ? 0 : 1, b)
+        if (!r.ok) throw new Error('rw_restore: ' + (r.error || 'restore failed'))
+        return {
+          text: `${r.mode === 'merge' ? 'Merged into' : 'Replaced'} ${target} from ${file} (${r.members} file(s) now present; the archive was verified before anything was written)${where === 'local' ? ' [from the local copy, uploaded first]' : ''}.`,
+        }
+      },
+    }),
   ]
 
   for (const t of tools) {
@@ -2528,6 +2790,38 @@ export async function apply(ctx, config) {
       sendJson, readBody, resolveRequestBinding, decodeBuf, encodeText, audit, config, mirrorDirFor,
     }),
 
+    ...createBackupRoutes({
+      sendJson,
+      readBody,
+      config,
+      audit,
+      resolveRequestBinding,
+      // The settings panel may act on a machine that is not the current one; the
+      // id is resolved to a real pool so a backup never runs against whichever
+      // machine happened to be active.
+      resolveMachineBinding: async (machineId) => {
+        const m = machines.find((x) => x.id === machineId)
+        if (!m) {
+          const err = new Error(`机器不存在：${machineId}`)
+          err.httpStatus = 404
+          throw err
+        }
+        const target = poolForMachine(identityOf(m))
+        return {
+          pool: target,
+          ws: String(m.workspace || ''),
+          host: m.host,
+          username: m.username,
+          port: Number(m.port) || 22,
+          alias: aliasOf(m),
+          mirrorDir: m.workspace ? mirrorDirFor(m.workspace, m.host, m.username, m.port) : null,
+          bound: false,
+          local: false,
+        }
+      },
+      localRootFor: localBackupRootFor,
+    }),
+
     {
       kind: 'exact',
       path: '/dsh-remote/workspace',

package/lib/pool.js

@@ -213,7 +213,20 @@ export class SshPool {
               finish(prompts.map(() => this.config.password || ''))
             })
           }
-          client.connect(opts)
+          // ssh2 parses the private key SYNCHRONOUSLY inside connect() and
+          // throws on an unparseable key (the classic case: an encrypted
+          // OpenSSH key without a passphrase). Left uncaught, that throw
+          // rejects this orphaned .then chain — an unhandled rejection that
+          // crashes the whole host process (issue #48: "dsh: fatal load
+          // failure" on every boot, because boot-restore re-dials the bad
+          // machine). It also leaves the outer promise pending forever.
+          // Convert it into a normal rejection so every caller's try/catch —
+          // boot restore, test-connect, rw_connect — sees a regular failure.
+          try {
+            client.connect(opts)
+          } catch (err) {
+            rejectOnce(err)
+          }
         },
         (err) => rejectOnce(err),
       )