@linxin666/dsh-ssh 0.1.19 → 0.2.0

package/src/client/panel/HostsTab.tsx

@@ -3,7 +3,7 @@
  * add/edit/delete/test actions, ~/.ssh/config import, and a connect action
  * that hands the alias to the terminal tab via onConnect.
  */
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
 import type { SshApi } from '../api.ts'
 import type { SshHostSummary, TestResult } from '../../protocol.ts'
 import { errorMessage, tt } from './helpers.ts'
@@ -20,6 +20,44 @@ export interface HostsTabProps {
 /** The host-form dialog invocation. */
 type DialogState = { mode: 'create' } | { mode: 'edit'; host: SshHostSummary }
 
+/** Host list grouping modes (#379). */
+export type HostGroupBy = 'none' | 'environment' | 'tags'
+
+/** One collapsible group section of the grouped host list. */
+export interface HostGroup {
+  /** Group key: the environment name, one tag, or '' for the ungrouped bucket. */
+  key: string
+  hosts: SshHostSummary[]
+}
+
+/**
+ * Bucket hosts into collapsible groups (#379). Grouping by tags places a
+ * multi-tag host in every one of its tag groups (folder view); hosts without
+ * the grouping key land in the '' bucket, which always sorts last. Groups
+ * sort alphabetically; host order inside a group follows the API listing.
+ */
+export function groupHosts(hosts: SshHostSummary[], groupBy: HostGroupBy): HostGroup[] {
+  if (groupBy === 'none') return [{ key: '', hosts }]
+  const buckets = new Map<string, SshHostSummary[]>()
+  const push = (key: string, host: SshHostSummary): void => {
+    const bucket = buckets.get(key)
+    if (bucket === undefined) buckets.set(key, [host])
+    else bucket.push(host)
+  }
+  for (const host of hosts) {
+    if (groupBy === 'environment') {
+      push(host.environment ?? '', host)
+    } else if (host.tags.length === 0) {
+      push('', host)
+    } else {
+      for (const tag of host.tags) push(tag, host)
+    }
+  }
+  return [...buckets.entries()]
+    .sort(([a], [b]) => (a === '' ? 1 : b === '' ? -1 : a.localeCompare(b)))
+    .map(([key, group]) => ({ key, hosts: group }))
+}
+
 /** The hosts table plus its toolbar and dialogs. */
 export function HostsTab({ api, onConnect }: HostsTabProps) {
   const [hosts, setHosts] = useState<SshHostSummary[] | null>(null)
@@ -30,6 +68,9 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
   const [importing, setImporting] = useState(false)
   const [notice, setNotice] = useState<string | null>(null)
   const [dialog, setDialog] = useState<DialogState | null>(null)
+  const [groupBy, setGroupBy] = useState<HostGroupBy>('none')
+  const [collapsed, setCollapsed] = useState<Record<string, boolean>>({})
+  const [testingGroup, setTestingGroup] = useState<string | null>(null)
   const seqRef = useRef(0)
 
   const load = useCallback(async (query?: string): Promise<void> => {
@@ -78,6 +119,16 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
     }
   }
 
+  // Group-header batch action (#379): test every host in the group.
+  const testGroup = async (group: HostGroup): Promise<void> => {
+    setTestingGroup(group.key)
+    try {
+      await Promise.all(group.hosts.map(host => runTest(host.alias)))
+    } finally {
+      setTestingGroup(null)
+    }
+  }
+
   const importConfig = async (): Promise<void> => {
     setImporting(true)
     try {
@@ -91,10 +142,73 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
     }
   }
 
+  const renderHostRow = (host: SshHostSummary): ReactNode => {
+    const test = testResults[host.alias]
+    return (
+      <tr key={host.alias}>
+        <td className={css.mono}>{host.alias}</td>
+        <td className={css.mono}>{host.host}:{host.port}</td>
+        <td>{host.user}</td>
+        <td><span className={css.badge} data-kind={host.auth}>{host.auth === 'key' ? tt('form.auth.key') : tt('form.auth.password')}</span></td>
+        <td className={css.cellMuted}>{host.environment ?? ''}</td>
+        <td className={css.cellMuted}>{host.tags.join(', ')}</td>
+        <td className={css.cellMuted}>{host.description ?? ''}</td>
+        <td>
+          <div className={css.actions}>
+            <button type="button" className={css.linkButton} disabled={testingAlias === host.alias} onClick={() => { void runTest(host.alias) }}>
+              {testingAlias === host.alias ? tt('hosts.testing') : tt('hosts.test')}
+            </button>
+            {testingAlias === host.alias && <span className={css.spinner} aria-hidden="true" />}
+            {test !== undefined && (
+              <span className={css.inlineTest} data-status={test.ok ? 'ok' : 'fail'}>
+                {test.ok ? tt('hosts.testOk', { latency: test.latencyMs ?? 0 }) : tt('hosts.testFail', { error: test.error ?? '' })}
+              </span>
+            )}
+            <button type="button" className={css.linkButton} onClick={() => { setDialog({ mode: 'edit', host }) }}>{tt('hosts.edit')}</button>
+            <button type="button" className={css.linkButton} data-danger onClick={() => { void deleteHost(host.alias) }}>{tt('hosts.delete')}</button>
+            <button type="button" className={css.ghostButton} onClick={() => { onConnect(host.alias) }}>{tt('hosts.connected')}</button>
+          </div>
+        </td>
+      </tr>
+    )
+  }
+
+  const renderHostTable = (rows: SshHostSummary[]): ReactNode => (
+    <table className={css.table}>
+      <thead>
+        <tr>
+          <th>{tt('hosts.col.alias')}</th>
+          <th>{tt('hosts.col.host')}</th>
+          <th>{tt('hosts.col.user')}</th>
+          <th>{tt('hosts.col.auth')}</th>
+          <th>{tt('hosts.col.environment')}</th>
+          <th>{tt('hosts.col.tags')}</th>
+          <th>{tt('hosts.col.description')}</th>
+          <th>{tt('hosts.col.actions')}</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map(renderHostRow)}
+      </tbody>
+    </table>
+  )
+
+  const groups = hosts === null ? [] : groupHosts(hosts, groupBy)
+
   return (
     <div className={css.fillBody}>
       <div className={css.toolbar}>
         <input className={css.search} type="search" placeholder={tt('hosts.search')} value={search} onChange={event => { setSearch(event.target.value) }} />
+        <select
+          className={css.groupBySelect}
+          aria-label={tt('hosts.groupBy.label')}
+          value={groupBy}
+          onChange={event => { setGroupBy(event.target.value as HostGroupBy) }}
+        >
+          <option value="none">{tt('hosts.groupBy.none')}</option>
+          <option value="environment">{tt('hosts.groupBy.environment')}</option>
+          <option value="tags">{tt('hosts.groupBy.tags')}</option>
+        </select>
         <div className={css.toolbarSpacer} />
         <button type="button" className={css.primaryButton} onClick={() => { setDialog({ mode: 'create' }) }}>{tt('hosts.add')}</button>
         <button type="button" className={css.ghostButton} disabled={importing} onClick={() => { void importConfig() }}>{importing ? tt('common.loading') : tt('hosts.import')}</button>
@@ -103,54 +217,44 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
       {error !== null && <div className={css.banner} data-kind="error">{tt('common.error', { error })}</div>}
       {hosts === null && error === null && <div className={css.loading}>{tt('common.loading')}</div>}
       {hosts !== null && hosts.length === 0 && <div className={css.empty}>{tt('hosts.empty')}</div>}
-      {hosts !== null && hosts.length > 0 && (
+      {hosts !== null && hosts.length > 0 && groupBy === 'none' && (
+        <div className={css.tableWrap}>
+          {renderHostTable(hosts)}
+        </div>
+      )}
+      {hosts !== null && hosts.length > 0 && groupBy !== 'none' && (
         <div className={css.tableWrap}>
-          <table className={css.table}>
-            <thead>
-              <tr>
-                <th>{tt('hosts.col.alias')}</th>
-                <th>{tt('hosts.col.host')}</th>
-                <th>{tt('hosts.col.user')}</th>
-                <th>{tt('hosts.col.auth')}</th>
-                <th>{tt('hosts.col.environment')}</th>
-                <th>{tt('hosts.col.tags')}</th>
-                <th>{tt('hosts.col.description')}</th>
-                <th>{tt('hosts.col.actions')}</th>
-              </tr>
-            </thead>
-            <tbody>
-              {hosts.map(host => {
-                const test = testResults[host.alias]
-                return (
-                  <tr key={host.alias}>
-                    <td className={css.mono}>{host.alias}</td>
-                    <td className={css.mono}>{host.host}:{host.port}</td>
-                    <td>{host.user}</td>
-                    <td><span className={css.badge} data-kind={host.auth}>{host.auth === 'key' ? tt('form.auth.key') : tt('form.auth.password')}</span></td>
-                    <td className={css.cellMuted}>{host.environment ?? ''}</td>
-                    <td className={css.cellMuted}>{host.tags.join(', ')}</td>
-                    <td className={css.cellMuted}>{host.description ?? ''}</td>
-                    <td>
-                      <div className={css.actions}>
-                        <button type="button" className={css.linkButton} disabled={testingAlias === host.alias} onClick={() => { void runTest(host.alias) }}>
-                          {testingAlias === host.alias ? tt('hosts.testing') : tt('hosts.test')}
-                        </button>
-                        {testingAlias === host.alias && <span className={css.spinner} aria-hidden="true" />}
-                        {test !== undefined && (
-                          <span className={css.inlineTest} data-status={test.ok ? 'ok' : 'fail'}>
-                            {test.ok ? tt('hosts.testOk', { latency: test.latencyMs ?? 0 }) : tt('hosts.testFail', { error: test.error ?? '' })}
-                          </span>
-                        )}
-                        <button type="button" className={css.linkButton} onClick={() => { setDialog({ mode: 'edit', host }) }}>{tt('hosts.edit')}</button>
-                        <button type="button" className={css.linkButton} data-danger onClick={() => { void deleteHost(host.alias) }}>{tt('hosts.delete')}</button>
-                        <button type="button" className={css.ghostButton} onClick={() => { onConnect(host.alias) }}>{tt('hosts.connected')}</button>
-                      </div>
-                    </td>
-                  </tr>
-                )
-              })}
-            </tbody>
-          </table>
+          {groups.map(group => {
+            const isCollapsed = collapsed[group.key] === true
+            const label = group.key === ''
+              ? (groupBy === 'tags' ? tt('hosts.group.noTags') : tt('hosts.group.ungrouped'))
+              : group.key
+            return (
+              <section key={group.key} className={css.groupSection}>
+                <div className={css.groupHeader}>
+                  <button
+                    type="button"
+                    className={css.groupToggle}
+                    aria-expanded={!isCollapsed}
+                    onClick={() => { setCollapsed(prev => ({ ...prev, [group.key]: !isCollapsed })) }}
+                  >
+                    <span className={css.groupChevron} data-collapsed={isCollapsed || undefined} aria-hidden="true" />
+                    <span className={css.groupName}>{label}</span>
+                    <span className={css.groupCount}>{tt('hosts.group.count', { count: group.hosts.length })}</span>
+                  </button>
+                  <button
+                    type="button"
+                    className={css.linkButton}
+                    disabled={testingGroup === group.key}
+                    onClick={() => { void testGroup(group) }}
+                  >
+                    {testingGroup === group.key ? tt('hosts.testing') : tt('hosts.group.testAll')}
+                  </button>
+                </div>
+                {!isCollapsed && renderHostTable(group.hosts)}
+              </section>
+            )
+          })}
         </div>
       )}
       {dialog !== null && (

package/src/client/panel/panel.module.css

@@ -242,6 +242,81 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
   color: var(--dsw-alias-label-tertiary);
 }
 
+.groupBySelect {
+  padding: 6px 8px;
+  font-size: 13px;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-specific-input-major);
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  outline: none;
+}
+
+/* --- host groups (#379) ------------------------------------------------------- */
+
+.groupSection + .groupSection {
+  border-top: 1px solid var(--dsw-alias-border-l1);
+}
+
+.groupHeader {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 8px;
+  position: sticky;
+  top: 0;
+  background: var(--dsw-alias-bg-base, var(--dsw-specific-input-major));
+}
+
+.groupToggle {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+  padding: 4px 6px;
+  border: none;
+  background: none;
+  color: var(--dsw-alias-label-primary);
+  font-size: 12.5px;
+  font-weight: 500;
+  cursor: pointer;
+  text-align: left;
+  border-radius: 6px;
+}
+
+.groupToggle:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.groupChevron {
+  width: 7px;
+  height: 7px;
+  border-right: 1.5px solid var(--dsw-alias-label-tertiary);
+  border-bottom: 1.5px solid var(--dsw-alias-label-tertiary);
+  transform: rotate(45deg);
+  transition: transform 120ms ease;
+  flex: none;
+  margin-bottom: 2px;
+}
+
+.groupChevron[data-collapsed] {
+  transform: rotate(-45deg);
+  margin-bottom: 0;
+}
+
+.groupName {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.groupCount {
+  color: var(--dsw-alias-label-tertiary);
+  font-weight: 400;
+  flex: none;
+}
+
 /* --- tables ------------------------------------------------------------------- */
 
 .tableWrap {

package/src/engine/connection-pool.ts

@@ -213,8 +213,13 @@ export function disposeRecord(engine: PoolEngine, alias: string, record?: PoolRe
   if (record !== undefined && current !== record) return
   if (current === undefined) return
   engine.pool.delete(alias)
-  try { current.client.end() } catch { /* already closed */ }
-  for (const hop of current.hops) {
+  endRecordChain(current)
+}
+
+/** End one record's client and hop chain (best-effort, safe to repeat). */
+export function endRecordChain(record: PoolRecord): void {
+  try { record.client.end() } catch { /* already closed */ }
+  for (const hop of record.hops) {
     try { hop.end() } catch { /* already closed */ }
   }
 }
@@ -247,6 +252,14 @@ export async function withClient<T>(engine: PoolEngine, alias: string, fn: (clie
       const result = await fn(record.client)
       record.idleAt = Date.now()
       return result
+    } catch (error) {
+      lastError = error
+      // Retry only when the connection actually broke mid-flight: drop the
+      // corpse and let the next attempt reconnect (a reconnect may replay a
+      // non-idempotent command — the documented trade-off). A failure on a
+      // healthy connection is a logic error and is rethrown, not replayed.
+      if (!record.broken) throw error
+      disposeRecord(engine, alias, record)
     } finally {
       record.inFlight -= 1
     }
@@ -297,8 +310,15 @@ export async function execCommand(engine: PoolEngine, alias: string, command: st
           if (settled) return
           settled = true
           clearTimeout(timer)
+          if (typeof code !== 'number' && !timedOut) {
+            // The channel closed without an exit status: the connection
+            // dropped mid-flight. Reject so withClient can reconnect and
+            // retry within the attempt budget.
+            reject(new Error('ssh: connection lost mid-flight (channel closed without an exit status)'))
+            return
+          }
           resolve({
-            success: code === 0 && !timedOut,
+            success: code === 0,
             exitCode: code,
             timedOut,
             stdout: stdout.text,

package/src/engine/sftp.ts

@@ -4,7 +4,7 @@
  * released exactly once so sshd's MaxSessions cap is never exhausted.
  */
 
-import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, readdirSync, statSync } from 'node:fs'
 import { dirname, join, relative, resolve as resolvePath } from 'node:path'
 import { Client, type SFTPWrapper } from 'ssh2'
 import type { RemoteDirEntry, TransferProgress } from '../protocol.ts'
@@ -16,7 +16,11 @@ export function walkLocalDir(root: string): string[] {
   const visit = (dir: string): void => {
     for (const name of readdirSync(dir)) {
       const full = join(dir, name)
-      const stat = statSync(full)
+      // lstat, not stat: a symlink must never be followed — a link cycle
+      // (ln -s . self) recurses forever under stat, and a link to a file
+      // would silently upload the target's bytes.
+      const stat = lstatSync(full)
+      if (stat.isSymbolicLink()) continue
       if (stat.isDirectory()) visit(full)
       else if (stat.isFile()) files.push(relative(root, full))
     }
@@ -169,13 +173,20 @@ function ensureRemoteDir(sftp: SFTPWrapper, remote: string): Promise<void> {
   })
 }
 
-function fastPut(sftp: SFTPWrapper, src: string, dst: string, concurrency: number, onProgress?: (progress: TransferProgress) => void): Promise<void> {
+/** One fastPut/fastGet transfer with throttled progress (the two directions share everything but the verb). */
+function fastTransfer(sftp: SFTPWrapper, kind: 'put' | 'get', src: string, dst: string, concurrency: number, onProgress?: (progress: TransferProgress) => void): Promise<void> {
   return new Promise((resolve, reject) => {
+    // Progress frames name the destination on upload, the source on download;
+    // the final size comes from the local side of the transfer.
+    const file = kind === 'put' ? dst : src
+    const finalSize = (): number => statSync(kind === 'put' ? src : dst).size
     let last = 0
     let lastEmit = 0
     const started = Date.now()
-    onProgress?.({ phase: 'transferring', file: dst, transferred: 0, total: statSync(src).size, percent: 0 })
-    sftp.fastPut(src, dst, { concurrency, step: (transferred: number, _chunk: number, total: number) => {
+    if (kind === 'put') {
+      onProgress?.({ phase: 'transferring', file, transferred: 0, total: statSync(src).size, percent: 0 })
+    }
+    const step = (transferred: number, _chunk: number, total: number): void => {
       const now = Date.now()
       // Throttle: high-speed links fire one callback per chunk; the UI only
       // needs ~10 frames per second.
@@ -184,52 +195,32 @@ function fastPut(sftp: SFTPWrapper, src: string, dst: string, concurrency: numbe
       const elapsed = (now - started) / 1000
       onProgress?.({
         phase: 'transferring',
-        file: dst,
+        file,
         transferred,
         total,
         percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0,
         speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : undefined,
       })
       last = transferred
-    } }, (error) => {
+    }
+    const done = (error: unknown): void => {
       if (error !== undefined) {
-        onProgress?.({ phase: 'error', file: dst, transferred: 0, total: 0, percent: 0, error: String(error) })
+        onProgress?.({ phase: 'error', file, transferred: 0, total: 0, percent: 0, error: String(error) })
         reject(error)
       } else {
-        onProgress?.({ phase: 'done', file: dst, transferred: statSync(src).size, total: statSync(src).size, percent: 100 })
+        onProgress?.({ phase: 'done', file, transferred: finalSize(), total: finalSize(), percent: 100 })
         resolve()
       }
-    })
+    }
+    if (kind === 'put') sftp.fastPut(src, dst, { concurrency, step }, done)
+    else sftp.fastGet(src, dst, { concurrency, step }, done)
   })
 }
 
+function fastPut(sftp: SFTPWrapper, src: string, dst: string, concurrency: number, onProgress?: (progress: TransferProgress) => void): Promise<void> {
+  return fastTransfer(sftp, 'put', src, dst, concurrency, onProgress)
+}
+
 function fastGet(sftp: SFTPWrapper, src: string, dst: string, concurrency: number, onProgress?: (progress: TransferProgress) => void): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let last = 0
-    let lastEmit = 0
-    const started = Date.now()
-    sftp.fastGet(src, dst, { concurrency, step: (transferred: number, _chunk: number, total: number) => {
-      const now = Date.now()
-      if (now - lastEmit < 100 && transferred < total) return
-      lastEmit = now
-      const elapsed = (now - started) / 1000
-      onProgress?.({
-        phase: 'transferring',
-        file: src,
-        transferred,
-        total,
-        percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0,
-        speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : undefined,
-      })
-      last = transferred
-    } }, (error) => {
-      if (error !== undefined) {
-        onProgress?.({ phase: 'error', file: src, transferred: 0, total: 0, percent: 0, error: String(error) })
-        reject(error)
-      } else {
-        onProgress?.({ phase: 'done', file: src, transferred: statSync(dst).size, total: statSync(dst).size, percent: 100 })
-        resolve()
-      }
-    })
-  })
+  return fastTransfer(sftp, 'get', src, dst, concurrency, onProgress)
 }

package/src/engine/tunnel.ts

@@ -6,13 +6,15 @@
 
 import { createServer, type Server as NetServer, type Socket } from 'node:net'
 import type { TunnelInfo } from '../protocol.ts'
-import { acquire, disposeRecord, type PoolEngine } from './connection-pool.ts'
+import { acquire, disposeRecord, endRecordChain, type PoolEngine, type PoolRecord } from './connection-pool.ts'
 
-/** One active tunnel record (server + pinned client + live sockets). */
+/** One active tunnel record (server + pinned connection + live sockets). */
 export interface TunnelRecord {
   info: TunnelInfo
   server: NetServer
   alias: string
+  /** The pooled connection this tunnel pins; siblings on one alias may share it. */
+  record: PoolRecord
   sockets: Set<Socket>
 }
 
@@ -48,7 +50,12 @@ export async function startTunnel(
     state: 'connecting',
     startedAt: Date.now(),
   }
-  const record = await acquire(engine, alias)
+  // Reuse the live pooled connection when one exists so sibling tunnels on
+  // one alias multiplex over it (and no orphaned connection leaks); recycle
+  // a broken one first.
+  const existing = engine.pool.get(alias)
+  if (existing !== undefined && existing.broken) disposeRecord(engine, alias, existing)
+  const record = engine.pool.get(alias) ?? (await acquire(engine, alias))
   const client = record.client
   const sockets = new Set<Socket>()
   const server = createServer((socket) => {
@@ -89,7 +96,7 @@ export async function startTunnel(
   const address = server.address()
   info.localPort = typeof address === 'object' && address !== null ? address.port : 0
   info.state = 'forwarding'
-  engine.tunnels.set(id, { info, server, alias, sockets })
+  engine.tunnels.set(id, { info, server, alias, record, sockets })
   return info
 }
 
@@ -108,7 +115,14 @@ export function stopTunnel(engine: TunnelEngine, id: string): boolean {
     try { socket.destroy() } catch { /* already closed */ }
   }
   tunnel.sockets.clear()
-  disposeRecord(engine, tunnel.alias)
+  // Sibling tunnels on the same alias share the pinned connection: release it
+  // only once the last tunnel using it is gone. A record the pool has since
+  // replaced (e.g. after a broken-connection recycle) is ended directly.
+  const shared = [...engine.tunnels.values()].some(candidate => candidate.record === tunnel.record)
+  if (!shared) {
+    if (engine.pool.get(tunnel.alias) === tunnel.record) disposeRecord(engine, tunnel.alias, tunnel.record)
+    else endRecordChain(tunnel.record)
+  }
   return true
 }
 

package/src/engine.ts

@@ -135,6 +135,17 @@ export class SshEngine {
     return stopAllTunnels(this, alias)
   }
 
+  /**
+   * Drop every live artifact bound to one alias: stop its tunnels and close
+   * the pooled connection. Host entries that are deleted or whose connection
+   * fields change must never keep serving a stale, previously authenticated
+   * connection — the next operation re-connects from the current config.
+   */
+  dropAlias(alias: string): void {
+    stopAllTunnels(this, alias)
+    disposeRecord(this, alias)
+  }
+
   // ------------------------------------------------------------- misc
 
   /** Probe connectivity: connect, run `true`, close. */

package/src/index.ts

@@ -18,6 +18,7 @@ import { SshEngine } from './engine.ts'
 import { makeRoutes } from './routes.ts'
 import { HostStore } from './store.ts'
 import { sshClusterTool, sshDownloadTool, sshExecTool, sshListTool, sshTunnelTool, sshUploadTool } from './tools.ts'
+import { mountOnce } from './mount-once.ts'
 
 /** Stable cordis plugin name. */
 export const name = 'ssh'
@@ -62,7 +63,9 @@ export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.
  * @param config - resolved plugin config (schema defaults applied by the loader).
  */
-export function apply(ctx: Context, config?: Config): void {
+export const apply = mountOnce('@linxin666/dsh-ssh', applyImpl)
+
+function applyImpl(ctx: Context, config?: Config): void {
   // The live source the surfaces read: the settings section once the web
   // settings surface is served, the composition entry otherwise.
   let current: () => Config = () => config ?? {}

package/src/mount-once.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+
+const MOUNTED = Symbol.for('dsh-web-ui.mounted-plugins')
+
+interface MountRegistry {
+  [MOUNTED]?: Set<string>
+}
+
+function mountedSet(): Set<string> {
+  const registry = globalThis as MountRegistry
+  return (registry[MOUNTED] ??= new Set())
+}
+
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
+  return ((...args: unknown[]) => {
+    const mounted = mountedSet()
+    if (mounted.has(packageName)) return
+    mounted.add(packageName)
+    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
+    ctx?.effect?.(() => () => {
+      mounted.delete(packageName)
+    })
+    return fn(...args)
+  }) as T
+}