dsh-remote 0.8.41 → 0.8.44

package/lib/index.js

@@ -40,6 +40,7 @@ import { syncTree, pushTree, loadSyncState, saveSyncState, pushOneFile } from '.
 import { searchRemote } from './search.js'
 import { resolveMirror, poolKey, lookupSessionCwd, encodeSegmentSafe, readSessionHeaderCwd, requestSessionHint } from './binding.js'
 import { TaskManager } from './tasks.js'
+import { DeployTasks } from './deploy-tasks.js'
 import { ForwardManager } from './forwards.js'
 import { WebAttach } from './web-attach.js'
 import {
@@ -51,7 +52,8 @@ import { selfDir, diskVersion, LOADED_VERSION, gtVersion, fetchLatestVersion, ap
 import { sendHeartbeat, pseudonym, heartbeatUrl, hasPersistedId, installIdPath } from './telemetry.js'
 import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeMachine as _sanitizeMachine, applyMachine as _applyMachine, machineId as _machineId } from './registry.js'
 import { registerHttpTransports } from './http-transport.js'
-import { SshPool } from './pool.js'
+import { SshPool, ActivePool, createPool } from './pool.js'
+import { isSystemOpenSshBackend, sshBinaryAvailable, resolveSshBinary } from './openssh.js'
 import { createFsRoutes } from './routes-fs.js'
 import { listDirStructured, removeRemoteTree } from './remote-fs.js'
 
@@ -109,6 +111,17 @@ export const Config = z.object({
   useAgent: z.boolean().default(false),
   /** Allow keyboard-interactive auth (OTP/MFA chains) using the configured password. */
   keyboardInteractive: z.boolean().default(false),
+  /** SSH transport backend (issue #51):
+   *  `native` (default) speaks SSH through ssh2 — password / private key /
+   *  ssh-agent / keyboard-interactive;
+   *  `openssh` delegates to the LOCAL `ssh` executable, which is the only way to
+   *  reach hosts that allow GSSAPI/Kerberos (kinit) or that rely on other
+   *  OpenSSH-only `~/.ssh/config` features (ProxyCommand, PKCS11Provider,
+   *  ControlMaster, Match blocks). See lib/openssh.js for the trade-offs. */
+  backend: z.string().default('native'),
+  /** The `ssh` executable the `openssh` backend drives (PATH name or a full
+   *  path). Ignored by the native backend. */
+  sshBinary: z.string().default(''),
   /** 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". */
@@ -315,7 +328,9 @@ function encodeText(s, enc) {
 // ── apply ─────────────────────────────────────────────────────────────────
 
 export async function apply(ctx, config) {
-  const pool = new SshPool(config, { knownHostsFile })
+  // The ACTIVE pool: a delegating facade, because `backend` is per machine and
+  // the plugin must keep ONE long-lived object to hang its hooks on (issue #51).
+  const pool = new ActivePool(config, { knownHostsFile })
   ctx.effect(() => () => pool.close(), 'dsh-remote.close')
 
   migrateLegacyData()
@@ -394,6 +409,50 @@ export async function apply(ctx, config) {
     }
   }
 
+  /**
+   * The CONNECT target for a pool, given a machine's RESOLVED connect identity
+   * (i.e. a record that already passed through withSshConfig()).
+   *
+   * Issue #38 resolves an alias machine into concrete host/user/port/key values
+   * because the native backend has to dial them itself. Issue #51's
+   * system-OpenSSH backend must NOT do that: it hands the name to `ssh`, and ssh
+   * matches its `Host` blocks against exactly the name it was given. Passing the
+   * resolved HostName instead would stop `Host myalias` blocks from matching and
+   * silently drop the very settings (GSSAPIAuthentication=yes, ProxyCommand,
+   * PKCS11Provider, Match blocks) that make this backend worth choosing. For an
+   * alias machine on that backend the ALIAS is therefore the connect target, no
+   * -l/-p/-i of our own is emitted, and ~/.ssh/config stays the single source of
+   * truth for that machine (which is also exactly what issue #50 asks for).
+   *
+   * @param {object} eff - a record after withSshConfig() (`sshAlias` present for
+   *   alias machines).
+   * @returns {{host: string, port: number, username: string, privateKeyPath: string, proxy: object|undefined, aliasNative: boolean}}
+   */
+  const connectTargetFor = (eff) => {
+    const aliasNative = !!(eff && eff.useSshConfig && isSystemOpenSshBackend(eff))
+    if (!aliasNative) {
+      return {
+        host: String((eff && eff.host) || ''),
+        port: Number((eff && eff.port) || 0) || 22,
+        username: String((eff && eff.username) || ''),
+        privateKeyPath: String((eff && eff.privateKeyPath) || ''),
+        proxy: eff && eff.proxy,
+        aliasNative: false,
+      }
+    }
+    const alias = String((eff && (eff.sshAlias || eff.host)) || '')
+    return {
+      // The alias itself; ssh expands HostName/User/Port/IdentityFile and every
+      // other directive while matching that Host block.
+      host: alias,
+      port: 0,            // 0 → no -p is emitted, so Port comes from the config
+      username: '',       // '' → no -l is emitted, so User comes from the config
+      privateKeyPath: '', // '' → no -i is emitted, so IdentityFile comes from it
+      proxy: undefined,   // a ProxyJump written in the config is honoured by ssh
+      aliasNative: true,
+    }
+  }
+
   /** The alias a machine was saved as ('' for a machine with literal values). */
   const aliasOf = (m) => (m && m.sshAlias) || (m && m.useSshConfig ? String(m.host || '') : '')
 
@@ -481,6 +540,9 @@ export async function apply(ctx, config) {
     passphrase: c.passphrase, workspace: c.workspace,
     useAgent: c.useAgent, keyboardInteractive: c.keyboardInteractive,
     proxy: c.proxy, hostKeyMode: c.hostKeyMode,
+    // Issue #51: the backend is part of the target identity, so a machine switch
+    // between backends must be seen as a change by setTarget.
+    backend: c.backend, sshBinary: c.sshBinary,
   })
 
   /** Fingerprint of the machine record last applied to the shared pool config.
@@ -512,6 +574,17 @@ export async function apply(ctx, config) {
     // OLD connection alive across a machine switch (issue #25 hazard).
     const previous = targetFields(config)
     applyMachine(config, { ...m, password: pw || m.password || '' })
+    // Issue #51: an ssh-config alias on the system-OpenSSH backend connects AS
+    // the alias, so ssh — not the plugin — expands HostName/User/Port/
+    // IdentityFile/ProxyJump, and the `Host` block keeps matching.
+    const t = connectTargetFor(m)
+    if (t.aliasNative) {
+      config.host = t.host
+      config.port = 22
+      config.username = ''
+      config.privateKeyPath = ''
+      config.proxy = undefined
+    }
     pool.setTarget(targetFields(config), previous)
     lastAppliedMachine = appliedFingerprint()
   }
@@ -595,28 +668,36 @@ export async function apply(ctx, config) {
     // effect for an existing session instead of dialing the stale address.
     const rec = machineRecordFor(target)
     const eff = rec ? withSshConfig(rec) : null
-    const host = (eff && eff.host) || target.host
-    const port = Number((eff && eff.port) || target.port) || 22
-    const username = (eff && eff.username) || target.username || 'root'
+    // Issue #51: on the system-OpenSSH backend an alias machine connects AS its
+    // alias so ~/.ssh/config (not the registry) supplies host/user/port/key.
+    const t = connectTargetFor(eff || target)
+    const host = t.aliasNative ? t.host : ((eff && eff.host) || target.host)
+    const port = t.aliasNative ? 0 : (Number((eff && eff.port) || target.port) || 22)
+    const username = t.aliasNative ? '' : ((eff && eff.username) || target.username || 'root')
     const existing = machinePools.get(key)
     if (existing) {
       syncTunables(existing.config)
-      // Re-point a live pool whose resolved identity moved (setTarget closes the
-      // connection, so only do it when something actually changed).
-      if (existing.config.host !== host || Number(existing.config.port) !== port || (existing.config.username || '') !== username) {
-        existing.setTarget({ host, port, username })
-      }
-      // Re-read credentials and per-machine policy from the registry: editing a
-      // machine in the settings page must reach a pool created earlier, and a
-      // pool holding a stale password would keep failing to reconnect.
+      // Credentials and per-machine policy are re-read from the registry BEFORE
+      // re-pointing: editing a machine in the settings page must reach a pool
+      // created earlier, and a pool holding a stale password would keep failing
+      // to reconnect. The backend belongs in this group too — ActivePool picks
+      // its delegate class from `config.backend` during setTarget/_sync, so
+      // assigning it afterwards would hand the OLD backend the new target.
       if (eff) {
         existing.config.password = eff.password || ''
-        existing.config.privateKeyPath = eff.privateKeyPath || ''
+        existing.config.privateKeyPath = t.aliasNative ? '' : (eff.privateKeyPath || '')
         existing.config.passphrase = eff.passphrase || ''
         existing.config.useAgent = !!eff.useAgent
         existing.config.keyboardInteractive = !!eff.keyboardInteractive
-        existing.config.proxy = eff.proxy || undefined
+        existing.config.proxy = t.aliasNative ? undefined : (eff.proxy || undefined)
         existing.config.hostKeyMode = eff.hostKeyMode || config.hostKeyMode
+        existing.config.backend = eff.backend || config.backend
+        existing.config.sshBinary = (typeof eff.sshBinary === 'string') ? eff.sshBinary : config.sshBinary
+      }
+      // Re-point a live pool whose resolved identity moved (setTarget closes the
+      // connection, so only do it when something actually changed).
+      if (existing.config.host !== host || Number(existing.config.port) !== port || (existing.config.username || '') !== username) {
+        existing.setTarget({ host, port, username })
       }
       return existing
     }
@@ -626,17 +707,22 @@ export async function apply(ctx, config) {
       port,
       username,
       password: (eff && eff.password) || '',
-      privateKeyPath: (eff && eff.privateKeyPath) || '',
+      privateKeyPath: t.aliasNative ? '' : ((eff && eff.privateKeyPath) || ''),
       passphrase: (eff && eff.passphrase) || '',
       useAgent: eff ? !!eff.useAgent : !!config.useAgent,
       keyboardInteractive: eff ? !!eff.keyboardInteractive : !!config.keyboardInteractive,
-      proxy: (eff && eff.proxy) || undefined,
+      proxy: t.aliasNative ? undefined : ((eff && eff.proxy) || undefined),
       hostKeyMode: (eff && eff.hostKeyMode) || config.hostKeyMode,
+      // Issue #51: the transport backend is a per-machine choice — an
+      // enterprise Kerberos host needs `openssh` while its neighbours stay on
+      // the native backend.
+      backend: (eff && eff.backend) || config.backend,
+      sshBinary: (eff && typeof eff.sshBinary === 'string') ? eff.sshBinary : config.sshBinary,
       // Identity-pinned pools never carry the shared active workspace: a
       // session passes its own mirror-resolved remote path explicitly.
       workspace: '',
     })
-    const created = new SshPool(poolConfig, { knownHostsFile })
+    const created = new ActivePool(poolConfig, { knownHostsFile })
     // Keychain-backed passwords resolve against THIS pool's machine record.
     created.passwordResolver = async () => machinePassword(eff || { id: '', password: poolConfig.password })
     machinePools.set(key, created)
@@ -849,6 +935,10 @@ export async function apply(ctx, config) {
   // starting a second remote server. Lifecycle is owned by the plugin fiber, so
   // unloading the plugin tears every tunnel down.
   const webAttaches = new Map() // machineId → WebAttach
+  // Deploy tasks run on the HOST, detached from any request: closing the browser
+  // window mid-install must not lose the progress, and a re-opened page must be
+  // able to re-attach and see the live state (high-availability requirement).
+  const deployTasks = new DeployTasks()
   ctx.effect(() => () => {
     for (const attach of webAttaches.values()) { try { attach.close() } catch { /* already gone */ } }
     webAttaches.clear()
@@ -956,6 +1046,69 @@ export async function apply(ctx, config) {
    *  without consulting the mutable active-machine state, so a concurrent
    *  session switching machines cannot redirect this session's commands. */
   const resolveMirrorForLocal = (local) => resolveMirror(local, remoteWorkspacesRoot())
+
+  /**
+   * The whole local-mirror registry with each mirror's recorded remote origin
+   * (issue #49).
+   *
+   * The sidebar's Session rows need to know, for EVERY visible row, whether that
+   * session is a remote one and which host it is bound to. Asking
+   * `/resolve-mirror` per row would issue one HTTP request per row and would
+   * also depend on the host still knowing that session id; instead the client
+   * already holds each row's cwd (the sessions snapshot) and matches it against
+   * this directory list locally, so the whole sidebar costs ONE request.
+   *
+   * Mirrors whose meta is missing/unparsable (or has no `host`) are SKIPPED
+   * rather than guessed at — the same rule `resolveMirror()` applies, and for
+   * the same reason: labelling a session with a host it is not bound to is
+   * worse than showing no badge at all.
+   *
+   * @returns {Array<{dir: string, host: string, port: number, username: string,
+   *   remotePath: string, alias: string, name: string}>} one entry per mirror.
+   */
+  const mirrorRegistry = () => {
+    const out = []
+    const root = remoteWorkspacesRoot()
+    if (!existsSync(root)) return out
+    let hostDirs = []
+    try { hostDirs = readdirSync(root) } catch { return out }
+    for (const hostDir of hostDirs) {
+      const hostPath = path.join(root, hostDir)
+      if (!statSync(hostPath, { throwIfNoEntry: false })?.isDirectory?.()) continue
+      let entries = []
+      try { entries = readdirSync(hostPath) } catch { continue }
+      for (const entry of entries) {
+        const dir = path.join(hostPath, entry)
+        const metaPath = path.join(dir, '.dsh-remote-meta.json')
+        if (!existsSync(metaPath)) continue
+        try {
+          const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
+          if (!meta || !meta.host) continue
+          const origin = {
+            host: String(meta.host),
+            port: Number(meta.port) || 22,
+            username: String(meta.username || ''),
+            alias: String(meta.alias || ''),
+          }
+          const rec = machineRecordFor(origin)
+          out.push({
+            dir: path.resolve(dir),
+            host: origin.host,
+            port: origin.port,
+            username: origin.username,
+            remotePath: String(meta.remotePath || ''),
+            alias: origin.alias,
+            // A saved machine's display name, when this mirror resolves to one:
+            // the UI prefers the friendly name over the raw address in its
+            // tooltip (the row itself shows the address, which is what the
+            // reader asked for).
+            name: rec && rec.name ? String(rec.name) : '',
+          })
+        } catch { /* unparsable meta → not a usable binding */ }
+      }
+    }
+    return out
+  }
   if (config.autoPush && wsPath()) {
     startAutoPush(mirrorDirFor(wsPath(), config.host, config.username, config.port))
   }
@@ -1345,7 +1498,7 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_connect',
       description:
-        '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.',
+        '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, backend, and ~/.ssh/config aliases; or (2) pass host plus any of username/port/password/privateKeyPath/passphrase/useAgent/keyboardInteractive/hostKeyMode/backend/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. For a host that only accepts GSSAPI/Kerberos (issue #51), pass backend="openssh" (with useSshConfig=true) so the local ssh — which holds your kinit ticket — performs the login. A failed connection is reported as an error message — it never takes the plugin down.',
       parameters: {
         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.' },
@@ -1357,6 +1510,8 @@ export async function apply(ctx, config) {
         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)' },
+        backend: { type: 'string', description: 'SSH transport backend (issue #51): "native" (default) uses the built-in ssh2 client (password / private key / agent / keyboard-interactive); "openssh" drives the LOCAL ssh command, which is the only way to reach hosts that require GSSAPI/Kerberos (log in once with kinit) and which honours the whole of ~/.ssh/config (ProxyCommand, PKCS11Provider, Match blocks). Prefer "openssh" together with useSshConfig=true so the alias and its settings stay the single source of truth.' },
+        sshBinary: { type: 'string', description: 'Path (or PATH name) of the ssh executable the "openssh" backend drives — default "ssh"' },
         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)' },
@@ -1398,10 +1553,17 @@ export async function apply(ctx, config) {
           if (args.keyboardInteractive !== undefined) rec.keyboardInteractive = !!args.keyboardInteractive
           if (args.hostKeyMode) rec.hostKeyMode = String(args.hostKeyMode)
           if (args.name) rec.name = String(args.name)
+          // Issue #51: pick the transport backend. `openssh` is what reaches
+          // GSSAPI/Kerberos-only hosts, and with useSshConfig=true the alias is
+          // handed to ssh verbatim so ~/.ssh/config stays the single source.
+          if (args.backend) rec.backend = args.backend === 'openssh' ? 'openssh' : 'native'
+          if (args.sshBinary !== undefined) rec.sshBinary = String(args.sshBinary)
           if (useSshConfig) rec.useSshConfig = true
           // An alias connection must dial the RESOLVED identity (~/.ssh/config),
-          // while the registry keeps the alias itself.
+          // while the registry keeps the alias itself — EXCEPT on the
+          // system-OpenSSH backend, where ssh resolves the alias itself.
           const eff = useSshConfig ? withSshConfig(rec) : rec
+          const ct = connectTargetFor(eff)
           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.
@@ -1434,15 +1596,19 @@ export async function apply(ctx, config) {
             // 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 || '',
+              // connectTargetFor: on the system-OpenSSH backend an alias machine
+              // dials the alias, not the values it expands to.
+              host: ct.host, port: ct.aliasNative ? 22 : (Number(eff.port) || port || 22), username: ct.aliasNative ? '' : (eff.username || user),
+              password: rec.password, privateKeyPath: ct.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,
+              proxy: ct.proxy,
+              backend: rec.backend || config.backend,
+              sshBinary: rec.sshBinary !== undefined ? rec.sshBinary : config.sshBinary,
               workspace: config.workspace,
             })
           }
@@ -1487,13 +1653,18 @@ export async function apply(ctx, config) {
           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')
+          // Issue #51: say which transport will be used — on `openssh` the
+          // credentials may come entirely from ~/.ssh/config (GSSAPI/kinit), so
+          // "auth: NONE" would be actively misleading there.
+          const backend = m.backend === 'openssh' ? 'openssh' : 'native'
+          if (backend === 'openssh') auth.push('openssh backend (~/.ssh/config: GSSAPI/key/agent)')
           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 `- ${m.id}  "${m.name || m.host}"  [${backend}]  ${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.' }
       },
@@ -2565,6 +2736,27 @@ export async function apply(ctx, config) {
         }
       },
     },
+    {
+      // Every local mirror with its recorded remote origin (issue #49).
+      //
+      // The sidebar paints a "this session is remote" mark on a Session row, so
+      // it needs the same mapping for every visible row. One directory listing
+      // answers all of them: the client matches each row's own cwd (which it
+      // already has in the sessions snapshot) against these mirror dirs, and a
+      // row whose cwd is inside a mirror is a remote session bound to that
+      // mirror's host. Never consults the mutable active machine — a saved
+      // machine that happens to be "current" must not label a local session.
+      kind: 'exact',
+      path: '/dsh-remote/bindings',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+        try {
+          return sendJson(res, 200, { mirrors: mirrorRegistry() })
+        } catch (err) {
+          return sendJson(res, 500, { error: String((err && err.message) || err) })
+        }
+      },
+    },
     {
       kind: 'exact',
       path: '/dsh-remote/connect',
@@ -2781,6 +2973,10 @@ export async function apply(ctx, config) {
                 hostKeyMode: body.hostKeyMode || '',
                 useAgent: !!body.useAgent,
                 keyboardInteractive: !!body.keyboardInteractive,
+                // Issue #51: the transport backend is per machine. `native` is
+                // the default, so an unknown value is not persisted as-is.
+                backend: body.backend === 'openssh' ? 'openssh' : 'native',
+                sshBinary: String(body.sshBinary || '').trim(),
                 proxy: body.proxy && body.proxy.host ? {
                   host: String(body.proxy.host),
                   port: Number(body.proxy.port) || 22,
@@ -2875,6 +3071,8 @@ export async function apply(ctx, config) {
           body = parseJsonObject(await readBody(req))
           // Issue #38: "test" on an ssh-config ALIAS resolves the alias first —
           // the form holds the alias name, not the host it points at.
+          const probeBackend = String(body.backend || config.backend || 'native')
+          const probeIsOpenssh = isSystemOpenSshBackend({ backend: probeBackend })
           const aliasTarget = body.useSshConfig
             ? resolveMachineSshConfig({
                 host: String(body.host || ''),
@@ -2885,15 +3083,20 @@ export async function apply(ctx, config) {
                 useSshConfig: true,
               }, { text: sshConfigText() })
             : null
-          const probe = new SshPool({
+          // Issue #51: on the system-OpenSSH backend an alias is handed to `ssh`
+          // VERBATIM (see connectTargetFor) — resolving it here would stop the
+          // `Host` block from matching, so the ~/.ssh/config settings the probe
+          // is supposed to validate would be silently skipped.
+          const probe = createPool({
             ...config,
-            host: aliasTarget ? aliasTarget.host : String(body.host || config.host),
-            port: aliasTarget ? aliasTarget.port : (Number(body.port) || config.port),
-            username: aliasTarget ? aliasTarget.username : String(body.username || config.username),
+            backend: probeBackend,
+            host: aliasTarget && !probeIsOpenssh ? aliasTarget.host : String(body.host || config.host),
+            port: aliasTarget && !probeIsOpenssh ? aliasTarget.port : (Number(body.port) || config.port),
+            username: aliasTarget && !probeIsOpenssh ? aliasTarget.username : String(body.username || config.username),
             password: String(body.password || ''),
-            privateKeyPath: aliasTarget ? aliasTarget.privateKeyPath : String(body.privateKeyPath || config.privateKeyPath),
+            privateKeyPath: (aliasTarget && !probeIsOpenssh) ? aliasTarget.privateKeyPath : String(body.privateKeyPath || config.privateKeyPath),
             passphrase: String(body.passphrase || ''),
-            proxy: aliasTarget && aliasTarget.proxy ? aliasTarget.proxy : (body.proxy && body.proxy.host ? {
+            proxy: (aliasTarget && !probeIsOpenssh && aliasTarget.proxy) ? aliasTarget.proxy : (body.proxy && body.proxy.host ? {
               host: String(body.proxy.host),
               port: Number(body.proxy.port) || 22,
               username: String(body.proxy.username || ''),
@@ -3076,10 +3279,15 @@ export async function apply(ctx, config) {
             const q = new URL(req.url, 'http://localhost').searchParams
             const id = q.get('machineId') || ''
             const attach = id ? webAttaches.get(id) : undefined
+            // Deploy tasks ride along so a REOPENED window sees an in-flight
+            // install immediately, without a separate poll's first tick.
+            const deploy = id ? deployTasks.forMachine(id) : null
             return sendJson(res, 200, {
               ok: true,
               attach: attach ? attach.describe() : null,
               attaches: [...webAttaches.values()].map((a) => a.describe()),
+              deploys: deployTasks.list(),
+              deploy: deploy ? deployTasks.describe(deploy) : null,
             })
           }
           if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
@@ -3124,75 +3332,113 @@ export async function apply(ctx, config) {
               })
             }
 
-            // install
+            // install — runs as a HOST-SIDE BACKGROUND TASK.
+            //
+            // It used to be one long HTTP request; npm can legitimately take
+            // minutes, and closing the tab mid-deploy lost the response AND
+            // every trace of the progress — the user could not tell whether it
+            // succeeded, and a second click started a CONCURRENT npm install
+            // into the same prefix. Now the work runs detached from the request
+            // lifecycle, every step's outcome is recorded as it happens, and
+            // the UI re-attaches by polling install-status (or by clicking the
+            // button again, which resumes rather than restarts).
             if (body.confirm !== true) {
               return sendJson(res, 400, { ok: false, error: '安装需要在请求里显式 confirm: true' })
             }
-            const pout = await target.exec(buildProbeCommand({ prefix, installedCommand, defaultPrefixFor: config.webInstallPrefix ? '' : 'home' }), { timeoutMs: 30000 })
-            const facts = parseProbe(pout && pout.stdout)
-            const verdict = judgeProbe(facts, { installedCommand })
-            if (!verdict.canAutoInstall) {
-              const why = verdict.findings.filter((x) => x.severity === 'blocker').map((x) => x.summary).join('；')
-              audit('web-deploy', `install ${machine.host} refused: ${why}`, 1, machine)
-              return sendJson(res, 400, { ok: false, error: `无法自动安装：${why || '远端缺少前提条件'}`, verdict })
+            // RESUME: a running/queued task for this machine is returned as-is.
+            // One deploy per machine at a time — two concurrent `npm --prefix`
+            // into the same directory corrupt the tree.
+            const already = deployTasks.forMachine(machineId)
+            if (already && (already.status === 'queued' || already.status === 'running') && body.force !== true) {
+              return sendJson(res, 200, { ok: true, resumed: true, task: deployTasks.describe(already) })
             }
-            const installPrefix = facts.resolvedPrefix || resolvePrefix(facts, { prefix: config.webInstallPrefix || '' })
-            // A registry the user set explicitly wins; otherwise the remote's own
-            // npm config is left alone, which is what an internal mirror needs.
-            // `--registry` is only added when configured — overriding a working
-            // corporate mirror with the public one would be a regression.
-            const registry = String(body.registry || config.webInstallRegistry || '').trim()
-            // Proxy comes from the remote's own environment; the operator may
-            // override it per-install when the inherited one is wrong.
-            const env = body.proxy && typeof body.proxy === 'object'
-              ? Object.fromEntries(Object.entries(body.proxy).filter(([, v]) => typeof v === 'string'))
-              : undefined
-            const plan = buildInstallPlan({
-              facts,
-              prefix: installPrefix,
-              version: String(body.version || config.webInstallVersion || DEFAULT_INSTALL_VERSION),
-              registry,
-              env,
-            })
-            const results = []
-            for (const step of plan.steps) {
-              let res2
-              try {
-                res2 = await target.exec(step.command, {
-                  timeoutMs: step.timeoutMs || 120000,
-                  // Per-step env exists for the proxy override (P4); pool.exec
-                  // passes it through to the remote process.
-                  ...(step.env ? { env: step.env } : {}),
-                })
-              } catch (err) {
-                results.push({ id: step.id, title: step.title, ok: false, code: -1, output: String((err && err.message) || err) })
-                break
-              }
-              const r = stepResult(step, res2)
-              results.push(r)
-              if (!r.ok) break
-            }
-            const ok = results.length === plan.steps.length && results.every((r) => r.ok)
-            if (ok) {
-              // Persist so the attach flow uses the working build from now on.
-              persistWebAttachCommand(machine, plan.command)
-              audit('web-deploy', `install ${machine.host} → ${plan.command}`, 0, machine)
-              return sendJson(res, 200, { ok: true, steps: results, command: plan.command, prefix: installPrefix })
+            if (already && body.force !== true && already.status !== 'done' && already.status !== 'failed' && already.status !== 'cancelled') {
+              return sendJson(res, 200, { ok: true, resumed: true, task: deployTasks.describe(already) })
             }
-            const failed = results.find((r) => !r.ok)
-            audit('web-deploy', `install ${machine.host} failed at ${failed && failed.id}`, 1, machine)
-            // A failure that looks like a network/registry problem gets the AI
-            // escape hatch suggested, since that is precisely the long tail the
-            // deterministic path cannot classify.
-            const looksNetworky = /ETIMEDOUT|ENOTFOUND|ECONNREFUSED|network|proxy|403|404/i.test(String(failed && failed.output))
-            return sendJson(res, 500, {
-              ok: false,
-              error: `安装失败于「${failed ? failed.title : '未知步骤'}」`,
-              steps: results,
-              prefix: installPrefix,
-              suggestInvestigate: true,
-              ...(looksNetworky ? { hint: '看起来是网络或源的问题，可以让 AI 排查。' } : {}),
+            const { task } = deployTasks.start(machineId, `deploy ${machine.host}`, async (ctx) => {
+              // Everything below is the SAME plan as before, but progress goes
+              // to the task (visible while it runs) instead of one response.
+              const pout = await target.exec(buildProbeCommand({ prefix, installedCommand, defaultPrefixFor: config.webInstallPrefix ? '' : 'home' }), { timeoutMs: 30000 })
+              const facts = parseProbe(pout && pout.stdout)
+              const verdict = judgeProbe(facts, { installedCommand })
+              if (!verdict.canAutoInstall) {
+                const why = verdict.findings.filter((x) => x.severity === 'blocker').map((x) => x.summary).join('；')
+                audit('web-deploy', `install ${machine.host} refused: ${why}`, 1, machine)
+                throw new Error(`无法自动安装：${why || '远端缺少前提条件'}`)
+              }
+              const installPrefix = facts.resolvedPrefix || resolvePrefix(facts, { prefix: config.webInstallPrefix || '' })
+              // A registry the user set explicitly wins; otherwise the remote's
+              // own npm config is left alone (internal mirrors keep working).
+              const registry = String(body.registry || config.webInstallRegistry || '').trim()
+              const env = body.proxy && typeof body.proxy === 'object'
+                ? Object.fromEntries(Object.entries(body.proxy).filter(([, v]) => typeof v === 'string'))
+                : undefined
+              const plan = buildInstallPlan({
+                facts,
+                prefix: installPrefix,
+                version: String(body.version || config.webInstallVersion || DEFAULT_INSTALL_VERSION),
+                registry,
+                env,
+              })
+              ctx.progress({ totalSteps: plan.steps.length, prefix: installPrefix })
+              const results = []
+              for (const step of plan.steps) {
+                if (ctx.cancelled) break
+                task.current = step.title
+                ctx.progress({ doneSteps: results.length })
+                let res2
+                try {
+                  res2 = await target.exec(step.command, {
+                    timeoutMs: step.timeoutMs || 120000,
+                    ...(step.env ? { env: step.env } : {}),
+                  })
+                } catch (err) {
+                  results.push({ id: step.id, title: step.title, ok: false, code: -1, output: String((err && err.message) || err) })
+                  break
+                }
+                const r = stepResult(step, res2)
+                results.push(r)
+                task.steps = [...results]
+                if (!r.ok) break
+              }
+              task.steps = [...results]
+              const ok = results.length === plan.steps.length && results.every((r) => r.ok)
+              if (ok) {
+                // Persist so the attach flow uses the working build from now on.
+                persistWebAttachCommand(machine, plan.command)
+                audit('web-deploy', `install ${machine.host} → ${plan.command}`, 0, machine)
+                return { ok: true, steps: results, command: plan.command, prefix: installPrefix }
+              }
+              const failed = results.find((r) => !r.ok)
+              audit('web-deploy', `install ${machine.host} failed at ${failed && failed.id}`, 1, machine)
+              const looksNetworky = /ETIMEDOUT|ENOTFOUND|ECONNREFUSED|network|proxy|403|404/i.test(String(failed && failed.output))
+              const err = new Error(`安装失败于「${failed ? failed.title : '未知步骤'}」`)
+              err.detail = {
+                steps: results,
+                prefix: installPrefix,
+                suggestInvestigate: true,
+                ...(looksNetworky ? { hint: '看起来是网络或源的问题，可以让 AI 排查。' } : {}),
+              }
+              throw err
             })
+            // Answer immediately: the task object IS the handle the UI polls.
+            return sendJson(res, 200, { ok: true, started: true, task: deployTasks.describe(task) })
+          }
+
+          // install-status: re-attach to a deploy at ANY time (window reopened,
+          // page refreshed). Also carried by GET /dsh-remote/web-attach.
+          if (action === 'install-status') {
+            const t = deployTasks.forMachine(machineId)
+            if (!t) return sendJson(res, 200, { ok: true, task: null })
+            return sendJson(res, 200, { ok: true, task: deployTasks.describe(t) })
+          }
+
+          // install-cancel: cooperative cancel between steps.
+          if (action === 'install-cancel') {
+            const t = deployTasks.forMachine(machineId)
+            if (!t) return sendJson(res, 200, { ok: true, cancelled: false })
+            const did = deployTasks.cancel(machineId)
+            return sendJson(res, 200, { ok: true, cancelled: did, task: deployTasks.describe(t) })
           }
 
           if (action === 'open') {