dsh-ssh-manage 0.2.1 → 0.2.2

package/README.en.md

@@ -96,16 +96,16 @@ Creating a host requires alias, hostname and password. The password is not writt
 
 ### From npm (recommended)
 
-npm package: [`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage) (current version `0.2.1`).
+npm package: [`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage) (current version `0.2.2`).
 
 ```text
-plugin_manager action=install_bundle target=dsh-ssh-manage@0.2.1
+plugin_manager action=install_bundle target=dsh-ssh-manage@0.2.2
 ```
 
 Or with the DSH CLI:
 
 ```bash
-dsh plugin add dsh-ssh-manage@0.2.1
+dsh plugin add dsh-ssh-manage@0.2.2
 ```
 
 After installation, refresh the Web page; the sidebar shows an "SSH Hosts" entry with id `dsh-ssh-manage`.
@@ -137,7 +137,7 @@ and make sure the package is resolvable by the profile (for example `link:` to t
 
 | | Requirement |
 | --- | --- |
-| **DSH** | **`>=0.2.1-rc.3 <0.3.0`** (validated on DSH Desktop `0.2.1-rc.3`) |
+| **DSH** | **`>=0.2.2-rc.3 <0.3.0`** (validated on DSH Desktop `0.2.2-rc.3`) |
 | **Node.js** | `>=20` (follows the DSH runtime) |
 | **Platform** | Validated on macOS; the test suite only uses Node built-ins and runs cross-platform |
 | **Network** | Reachable SSH port (22 by default, or the configured port) |

package/README.md

@@ -98,16 +98,16 @@
 
 ### 从 npm 安装（推荐）
 
-npm 包：[`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage)（当前版本 `0.2.1`）。
+npm 包：[`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage)（当前版本 `0.2.2`）。
 
 ```text
-plugin_manager action=install_bundle target=dsh-ssh-manage@0.2.1
+plugin_manager action=install_bundle target=dsh-ssh-manage@0.2.2
 ```
 
 或使用 DSH CLI：
 
 ```bash
-dsh plugin add dsh-ssh-manage@0.2.1
+dsh plugin add dsh-ssh-manage@0.2.2
 ```
 
 安装后刷新 Web 页面，左侧栏会出现「SSH 主机」入口，入口 id 为 `dsh-ssh-manage`。
@@ -139,7 +139,7 @@ plugin_manager action=install_bundle target=<仓库绝对路径>/dsh-ssh-manage
 
 | | 要求 |
 | --- | --- |
-| **DSH** | **`>=0.2.1-rc.3 <0.3.0`**（实机验证版本：DSH Desktop `0.2.1-rc.3`） |
+| **DSH** | **`>=0.2.2-rc.3 <0.3.0`**（实机验证版本：DSH Desktop `0.2.2-rc.3`） |
 | **Node.js** | `>=20`（跟随 DSH 内置运行时） |
 | **平台** | 实机验证 macOS；测试套件只依赖 Node 内置模块，可跨平台运行 |
 | **网络** | 需要能访问目标 SSH 主机的 22 端口（或配置的端口） |

package/client.js

@@ -16,6 +16,8 @@ window.__ModuleLoader__.load({
       panel: ['SSH 主机', 'SSH Hosts'],
       'tabs.hosts': ['主机', 'Hosts'],
       'tabs.sessions': ['会话', 'Sessions'],
+      'session.restoring': ['正在恢复终端会话…', 'Restoring terminal sessions…'],
+      'session.tooMany': ['最多同时打开 16 个终端会话，请先关闭一个。', 'At most 16 terminal sessions can be open. Close one first.'],
       'tabs.batch': ['批量命令', 'Batch'],
       'tabs.settings': ['设置', 'Settings'],
       'session.new': ['新建连接', 'New connection'],
@@ -141,6 +143,7 @@ window.__ModuleLoader__.load({
       'editor.required': ['请填写别名和服务器地址。', 'Alias and hostname are required.'],
       'editor.invalidAlias': ['别名只能包含字母、数字、点、下划线、@ 和短横线。', 'Alias may only contain letters, digits, dot, underscore, @ and dash.'],
       'editor.delete': ['删除这台主机', 'Delete this host'],
+      'editor.discardChanges': ['有未保存的修改，确定放弃？', 'Discard unsaved changes?'],
       'drawer.files': ['文件', 'Files'],
       'drawer.details': ['详情', 'Details'],
       'terminal.loading': ['正在加载终端…', 'Loading terminal…'],
@@ -1180,6 +1183,8 @@ window.__ModuleLoader__.load({
       const [clearSignals, setClearSignals] = React.useState({})
       const toastTimer = React.useRef(null)
       const floatingRef = React.useRef(null)
+      const editorCloseGuard = React.useRef(null)
+      const groupsCloseGuard = React.useRef(null)
 
       const notify = React.useCallback((message, tone = 'info') => {
         if (toastTimer.current) clearTimeout(toastTimer.current)
@@ -1375,6 +1380,10 @@ window.__ModuleLoader__.load({
         if (existing) {
           setActiveSessionId(existing.id)
         } else {
+          if (sessions.length >= MAX_TERMINAL_SESSIONS) {
+            notify(t('session.tooMany'), 'error')
+            return
+          }
           const id = newPtySessionId()
           ptyActiveIds.add(id)
           setSessions((prev) => [...prev, { id, hostAlias: host.host }])
@@ -1402,6 +1411,7 @@ window.__ModuleLoader__.load({
       }
 
       function clearSession(id) {
+        clearPtySession(id)
         setClearSignals((prev) => ({ ...prev, [id]: (prev[id] ?? 0) + 1 }))
       }
 
@@ -1584,11 +1594,15 @@ window.__ModuleLoader__.load({
             return
           }
           if (editor) {
-            setEditor(null)
+            const guard = editorCloseGuard.current
+            if (typeof guard === 'function') guard()
+            else setEditor(null)
             return
           }
           if (groupsOpen) {
-            setGroupsOpen(false)
+            const guard = groupsCloseGuard.current
+            if (typeof guard === 'function') guard()
+            else setGroupsOpen(false)
             return
           }
           if (drawer) setDrawer(null)
@@ -1680,6 +1694,8 @@ window.__ModuleLoader__.load({
         setFloating,
         setEditor,
         setDrawer,
+        editorCloseGuard,
+        groupsCloseGuard,
         treeWidth,
         setTreeWidth,
         sessions,
@@ -1934,7 +1950,7 @@ window.__ModuleLoader__.load({
               'div',
               { className: 'ssh-loadingPage' },
               h(Spinner, { size: 22 }),
-              h('span', null, t('state.loading')),
+              h('span', null, sessions.length > 0 ? t('session.restoring') : t('state.loading')),
             )
           : !snapshot && error
             ? h(
@@ -1951,7 +1967,7 @@ window.__ModuleLoader__.load({
                 : effectiveTab === 'batch'
                   ? h(BatchTab, { model })
                   : h(SettingsTab, { model }),
-        sessions.length > 0
+        snapshot && sessions.length > 0
           ? h(
               'div',
               { className: 'ssh-sessionLayer', style: { display: effectiveTab === 'sessions' ? 'flex' : 'none' } },
@@ -3039,11 +3055,73 @@ window.__ModuleLoader__.load({
       }
     }
 
+    const terminalThemeListeners = new Set()
+    let terminalThemeObserver = null
+    let terminalThemeMedia = null
+    let terminalThemeScheduled = false
+
+    function emitTerminalTheme() {
+      for (const listener of [...terminalThemeListeners]) {
+        try { listener() } catch {}
+      }
+    }
+
+    function scheduleTerminalTheme() {
+      if (terminalThemeScheduled) return
+      terminalThemeScheduled = true
+      const run = () => {
+        terminalThemeScheduled = false
+        emitTerminalTheme()
+      }
+      if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run)
+      else setTimeout(run, 16)
+    }
+
+    function ensureTerminalThemeWatcher() {
+      if (typeof MutationObserver !== 'undefined' && !terminalThemeObserver) {
+        terminalThemeObserver = new MutationObserver(scheduleTerminalTheme)
+        const options = {
+          attributes: true,
+          attributeFilter: ['class', 'style', 'data-theme', 'data-color-mode', 'data-ds-dark-theme', 'data-ds-theme-source'],
+        }
+        terminalThemeObserver.observe(document.documentElement, options)
+        if (document.body) terminalThemeObserver.observe(document.body, options)
+      }
+      if (typeof window !== 'undefined' && typeof window.matchMedia === 'function' && !terminalThemeMedia) {
+        terminalThemeMedia = window.matchMedia('(prefers-color-scheme: dark)')
+        const onChange = () => scheduleTerminalTheme()
+        if (typeof terminalThemeMedia.addEventListener === 'function') terminalThemeMedia.addEventListener('change', onChange)
+        else if (typeof terminalThemeMedia.addListener === 'function') terminalThemeMedia.addListener(onChange)
+        terminalThemeMedia.__sshThemeChange = onChange
+      }
+    }
+
+    function subscribeTerminalTheme(listener) {
+      terminalThemeListeners.add(listener)
+      ensureTerminalThemeWatcher()
+      return () => {
+        terminalThemeListeners.delete(listener)
+        if (terminalThemeListeners.size > 0) return
+        if (terminalThemeObserver) {
+          terminalThemeObserver.disconnect()
+          terminalThemeObserver = null
+        }
+        if (terminalThemeMedia) {
+          const onChange = terminalThemeMedia.__sshThemeChange
+          if (typeof terminalThemeMedia.removeEventListener === 'function') terminalThemeMedia.removeEventListener('change', onChange)
+          else if (typeof terminalThemeMedia.removeListener === 'function') terminalThemeMedia.removeListener(onChange)
+          terminalThemeMedia = null
+        }
+      }
+    }
+
     const PTY_EVENTS_ROUTE = '/dsh-ssh-manage/pty/events'
     const PTY_ATTACH_ROUTE = '/dsh-ssh-manage/pty/attach'
+    const PTY_CLEAR_ROUTE = '/dsh-ssh-manage/pty/clear'
     const ptyStream = { source: null, ready: false, promise: null, listeners: new Map() }
     const ptyActiveIds = new Set()
     const ptyClosedIds = new Set()
+    const MAX_TERMINAL_SESSIONS = 16
     const ptyStreamLostHandlers = new Set()
 
     function closePtySession(id) {
@@ -3065,13 +3143,23 @@ window.__ModuleLoader__.load({
       return () => ptyStreamLostHandlers.delete(handler)
     }
 
-    function resetPtyStream() {
+    function resetPtyStream(reason = new Error('Terminal event stream closed')) {
+      const wasReady = ptyStream.ready === true
+      const rejectPending = ptyStream.reject
+      ptyStream.reject = null
       if (ptyStream.source) {
         try { ptyStream.source.close() } catch {}
       }
       ptyStream.source = null
       ptyStream.ready = false
       ptyStream.promise = null
+      if (rejectPending) {
+        try { rejectPending(reason) } catch {}
+      }
+      // A stream that never finished connecting is not a lost terminal yet;
+      // its waiting panes get the rejected ensure promise and keep their
+      // normal connecting/error overlay.
+      if (!wasReady) return
       for (const handler of [...ptyStreamLostHandlers]) {
         try { handler() } catch {}
       }
@@ -3085,8 +3173,18 @@ window.__ModuleLoader__.load({
     }
 
     function ensurePtyStream() {
-      if (ptyStream.ready && ptyStream.source && ptyStream.source.readyState === 1) return Promise.resolve()
-      if (ptyStream.source && ptyStream.source.readyState !== 1) resetPtyStream()
+      if (ptyStream.source) {
+        const state = ptyStream.source.readyState
+        if (state === 1 && ptyStream.ready) return Promise.resolve()
+        // CONNECTING: all callers must share the one in-flight promise; never
+        // tear it down. This is the multi-tab restore / rapid-second-connect
+        // race that used to leave N-1 panes in a permanent error overlay.
+        if (state === 0) {
+          if (ptyStream.promise) return ptyStream.promise
+          try { ptyStream.source.close() } catch {}
+          ptyStream.source = null
+        } else if (state === 2) resetPtyStream()
+      }
       if (ptyStream.promise) return ptyStream.promise
       ptyStream.promise = new Promise((resolve, reject) => {
         let settled = false
@@ -3100,14 +3198,17 @@ window.__ModuleLoader__.load({
           ptyStream.source = null
           ptyStream.ready = false
           ptyStream.promise = null
+          ptyStream.reject = null
           reject(error)
         }
         ptyStream.source = source
+        ptyStream.reject = reject
         timer = setTimeout(() => fail(new Error('Terminal event stream timed out')), 10_000)
         source.addEventListener('open', () => {
           if (settled) return
           settled = true
           clearTimeout(timer)
+          ptyStream.reject = null
           ptyStream.ready = true
           resolve()
         })
@@ -3161,6 +3262,11 @@ window.__ModuleLoader__.load({
       }
     }
 
+    function clearPtySession(id) {
+      if (!id) return
+      void ptyPost(PTY_CLEAR_ROUTE, { id }, 15_000).catch(() => {})
+    }
+
     function decodeBase64(text) {
       const binary = atob(String(text ?? ''))
       const bytes = new Uint8Array(binary.length)
@@ -3179,6 +3285,8 @@ window.__ModuleLoader__.load({
       const [status, setStatus] = React.useState('loading')
       const [message, setMessage] = React.useState('')
       const [retryToken, setRetryToken] = React.useState(0)
+      const clearRequested = React.useRef(false)
+      const syncedRef = React.useRef(false)
 
       React.useEffect(() => {
         activeRef.current = active === true
@@ -3194,7 +3302,12 @@ window.__ModuleLoader__.load({
       }, [active])
 
       React.useEffect(() => {
-        if (!clearSignal || !termRef.current) return
+        if (!clearSignal) return
+        // Only a clear issued before attach needs to survive into the attach
+        // replay. A clear on a live, synced terminal is handled by the server
+        // route directly and must not truncate the next attach replay.
+        clearRequested.current = syncedRef.current !== true
+        if (!termRef.current) return
         try {
           termRef.current.clear()
           termRef.current.write('\x1b[H\x1b[2J')
@@ -3217,6 +3330,8 @@ window.__ModuleLoader__.load({
         let opened = false
         let inputChain = Promise.resolve()
         let streamLost = null
+        let themeUnsub = null
+        syncedRef.current = false
         setStatus('loading')
         setMessage('')
 
@@ -3278,6 +3393,10 @@ window.__ModuleLoader__.load({
           termRef.current = term
           fitRef.current = fit
           try { fit.fit() } catch {}
+          themeUnsub = subscribeTerminalTheme(() => {
+            if (removed || !term) return
+            try { term.options.theme = terminalThemeFor(container) } catch {}
+          })
           term.onData((data) => {
             const id = sessionKey
             if (!id || !data || !opened) return
@@ -3327,6 +3446,14 @@ window.__ModuleLoader__.load({
           let lastSeq = 0
           const pendingEvents = []
 
+          const clearTerminal = () => {
+            if (!term) return
+            try {
+              term.clear()
+              term.write('\x1b[H\x1b[2J')
+            } catch {}
+          }
+
           const applyOutput = (event) => {
             const seq = Number(event.seq)
             if (Number.isFinite(seq)) {
@@ -3340,6 +3467,9 @@ window.__ModuleLoader__.load({
             if (event.kind === 'output') {
               if (!synced) pendingEvents.push(event)
               else applyOutput(event)
+            } else if (event.kind === 'clear') {
+              if (!synced) pendingEvents.push(event)
+              else clearTerminal()
             } else if (event.kind === 'exit') {
               if (!synced) {
                 pendingEvents.push(event)
@@ -3386,18 +3516,23 @@ window.__ModuleLoader__.load({
               closePtySession(id)
               return
             }
-            if (removed) return
-            if (value && value.output) {
+            if (removed || stopped || finished) return
+            if (clearRequested.current) {
+              clearRequested.current = false
+              clearTerminal()
+              clearPtySession(id)
+            } else if (value && value.output) {
               try { term.write(decodeBase64(value.output)) } catch {}
             }
             const seq = Number(value?.seq)
             if (Number.isFinite(seq)) lastSeq = seq
             synced = true
             for (const event of pendingEvents.splice(0)) {
-              if (finished) break
+              if (finished || stopped) break
               handleEvent(event)
             }
-            if (finished) return
+            if (finished || stopped || removed) return
+            syncedRef.current = true
             opened = true
             setStatus('ready')
             setMessage('')
@@ -3422,6 +3557,7 @@ window.__ModuleLoader__.load({
 
         return () => {
           removed = true
+          if (themeUnsub) themeUnsub()
           if (streamLost) streamLost()
           if (resizeObserver) resizeObserver.disconnect()
           teardown()
@@ -3809,6 +3945,28 @@ window.__ModuleLoader__.load({
         setDraft((prev) => ({ ...prev, [field]: value }))
       }
 
+      const dirty = password !== '' || JSON.stringify(draft) !== JSON.stringify(state.draft)
+      const requestClose = () => {
+        if (busy) return
+        if (!dirty) {
+          model.setEditor(null)
+          return
+        }
+        let discard = true
+        try {
+          discard = typeof window.confirm !== 'function' || window.confirm(t('editor.discardChanges'))
+        } catch {}
+        if (discard) model.setEditor(null)
+      }
+
+      React.useEffect(() => {
+        const guard = () => requestClose()
+        model.editorCloseGuard.current = guard
+        return () => {
+          if (model.editorCloseGuard.current === guard) model.editorCloseGuard.current = null
+        }
+      })
+
       async function submit() {
         const alias = draft.host.trim()
         const hostname = draft.hostname.trim()
@@ -3864,7 +4022,7 @@ window.__ModuleLoader__.load({
               t('editor.delete'),
             )
           : h('span', { key: 'spacer', className: 'ssh-toolSpacer' }),
-        h(Button, { key: 'cancel', onClick: () => model.setEditor(null), disabled: busy }, t('common.cancel')),
+        h(Button, { key: 'cancel', onClick: requestClose, disabled: busy }, t('common.cancel')),
         h(
           Button,
           { key: 'save', variant: 'primary', onClick: () => void submit(), disabled: busy },
@@ -3881,7 +4039,7 @@ window.__ModuleLoader__.load({
           width: 700,
           icon: h(IconTerminal, { size: 16 }),
           closeLabel: t('common.close'),
-          onClose: () => model.setEditor(null),
+          onClose: requestClose,
           footer,
         },
         h(
@@ -4004,6 +4162,17 @@ window.__ModuleLoader__.load({
       const groups = buildGroups(hosts, t).filter((group) => group.key !== '')
       const [drafts, setDrafts] = React.useState(() => Object.fromEntries(groups.map((group) => [group.key, group.key])))
       const busy = isPending('groups')
+      const requestClose = () => {
+        if (!busy) model.setGroupsOpen(false)
+      }
+
+      React.useEffect(() => {
+        const guard = () => requestClose()
+        model.groupsCloseGuard.current = guard
+        return () => {
+          if (model.groupsCloseGuard.current === guard) model.groupsCloseGuard.current = null
+        }
+      })
 
       async function commit(name) {
         const next = String(drafts[name] ?? '').trim()
@@ -4020,8 +4189,8 @@ window.__ModuleLoader__.load({
           width: 560,
           icon: h(IconFolder, { size: 16 }),
           closeLabel: t('common.close'),
-          onClose: () => model.setGroupsOpen(false),
-          footer: [h(Button, { key: 'close', onClick: () => model.setGroupsOpen(false) }, t('common.close'))],
+          onClose: requestClose,
+          footer: [h(Button, { key: 'close', onClick: requestClose }, t('common.close'))],
         },
         groups.length === 0
           ? h('div', { className: 'ssh-sectionHint' }, t('groups.empty'))

package/index.js

@@ -17,6 +17,7 @@ const PTY_INPUT_ROUTE = '/dsh-ssh-manage/pty/input'
 const PTY_RESIZE_ROUTE = '/dsh-ssh-manage/pty/resize'
 const PTY_ATTACH_ROUTE = '/dsh-ssh-manage/pty/attach'
 const PTY_CLOSE_ROUTE = '/dsh-ssh-manage/pty/close'
+const PTY_CLEAR_ROUTE = '/dsh-ssh-manage/pty/clear'
 const MAX_PTY_SESSIONS = 16
 const PTY_BUFFER_BYTES = 256 * 1024
 const PTY_IDLE_MS = 6 * 60 * 60 * 1000
@@ -75,14 +76,26 @@ function errorMessage(error) {
 }
 
 async function state(paths) {
-  const [current, metadata, passwords] = await Promise.all([listSshHosts(paths), loadMetadata(paths), listPasswordAliases(paths)])
+  const [current, metadataResult, passwordsResult] = await Promise.all([
+    listSshHosts(paths),
+    loadMetadata(paths).then((value) => ({ value }), (error) => ({ error })),
+    listPasswordAliases(paths).then((value) => ({ value }), (error) => ({ error })),
+  ])
+  const warnings = []
+  let entries = {}
+  if ('error' in metadataResult) warnings.push({ store: 'metadata', message: errorMessage(metadataResult.error) })
+  else entries = metadataResult.value.entries
+  let passwords = []
+  if ('error' in passwordsResult) warnings.push({ store: 'vault', message: errorMessage(passwordsResult.error) })
+  else passwords = passwordsResult.value
   const passwordSet = new Set(passwords)
   const stateDir = storagePaths(paths).stateDir
   return {
     ...current,
     stateDir,
     backupDir: paths.backupDir || path.join(stateDir, 'backups'),
-    hosts: current.hosts.map((host) => ({ ...host, ...(metadata.entries[host.host] || {}), passwordConfigured: passwordSet.has(host.host) })),
+    hosts: current.hosts.map((host) => ({ ...host, ...(entries[host.host] || {}), passwordConfigured: passwordSet.has(host.host) })),
+    warnings,
   }
 }
 
@@ -282,6 +295,16 @@ const ptyPendingIds = new Set()
 const ptyEventClients = new Set()
 let ptyOpening = 0
 
+function createPtyRuntime() {
+  return { generation: 0, active: true, upgrades: new Set() }
+}
+
+const defaultPtyRuntime = createPtyRuntime()
+
+function isPtyRuntimeActive(runtime, generation) {
+  return runtime.active && runtime.generation === generation
+}
+
 function closeTextSession(id, notify = true) {
   const entry = ptyTextSessions.get(id)
   if (!entry) return
@@ -311,15 +334,17 @@ function broadcastPty(event) {
   for (const client of [...ptyEventClients]) writePtyEvent(client, event)
 }
 
-async function openTextSession(paths, payload) {
+async function openTextSession(paths, payload, runtime = defaultPtyRuntime) {
+  if (!runtime.active) throw new Error('Terminal runtime is not active')
   const id = typeof payload?.id === 'string' ? payload.id.trim() : ''
   if (!/^[A-Za-z0-9_-]{8,80}$/.test(id)) throw new Error('A valid session id is required')
+  const cols = boundedInteger(payload?.cols, 20, 500, 120)
+  const rows = boundedInteger(payload?.rows, 5, 300, 32)
+  const alias = typeof payload?.host === 'string' ? payload.host.trim() : ''
+  if (alias === '') throw new Error('host is required')
   if (ptyTextSessions.has(id) || ptyPendingIds.has(id)) throw new Error('Terminal session already exists')
+  const generation = runtime.generation
   ptyPendingIds.add(id)
-  const cols = boundedInteger(payload.cols, 20, 500, 120)
-  const rows = boundedInteger(payload.rows, 5, 300, 32)
-  const alias = typeof payload.host === 'string' ? payload.host.trim() : ''
-  if (alias === '') throw new Error('host is required')
   ptyOpening += 1
   try {
     if (ptySessions.size + ptyTextSessions.size + ptyOpening > MAX_PTY_SESSIONS) {
@@ -327,7 +352,12 @@ async function openTextSession(paths, payload) {
     }
     const host = await findHost(paths, alias)
     const password = await requirePassword(paths, host)
+    if (!isPtyRuntimeActive(runtime, generation)) throw new Error('Terminal runtime is not active')
     const session = await openPty(host, password, { cols, rows })
+    if (!isPtyRuntimeActive(runtime, generation)) {
+      try { session.close() } catch {}
+      throw new Error('Terminal runtime is not active')
+    }
     if (ptyTextSessions.has(id)) {
       try { session.close() } catch {}
       throw new Error('Terminal session already exists')
@@ -363,7 +393,7 @@ async function openTextSession(paths, payload) {
   }
 }
 
-function registerPtyHttpRoutes(ctx, paths) {
+function registerPtyHttpRoutes(ctx, paths, runtime) {
   const register = (route, label) => {
     ctx.effect(() => ctx.webServer.register(route), `dsh-ssh-manage: ${label}`)
   }
@@ -423,7 +453,7 @@ function registerPtyHttpRoutes(ctx, paths) {
         }
         const body = await readJsonBody(req)
         try {
-          const value = await openTextSession(paths, body ?? {})
+          const value = await openTextSession(paths, body ?? {}, runtime)
           sendJson(res, 200, { ok: true, value })
         } catch (error) {
           sendJson(res, 200, { ok: false, error: { code: 'pty-open-failed', message: errorMessage(error) } })
@@ -473,6 +503,7 @@ function registerPtyHttpRoutes(ctx, paths) {
     [PTY_INPUT_ROUTE, 'input', 'pty input route'],
     [PTY_RESIZE_ROUTE, 'resize', 'pty resize route'],
     [PTY_CLOSE_ROUTE, 'close', 'pty close route'],
+    [PTY_CLEAR_ROUTE, 'clear', 'pty clear route'],
   ]) {
     register(
       {
@@ -504,6 +535,10 @@ function registerPtyHttpRoutes(ctx, paths) {
                 0,
                 0,
               )
+            } else if (action === 'clear') {
+              entry.buffer = []
+              entry.bufferBytes = 0
+              broadcastPty({ kind: 'clear', id })
             } else {
               closeTextSession(id)
             }
@@ -554,7 +589,11 @@ function upgradeRejection(ctx, req) {
   return rejection === undefined ? undefined : rejection
 }
 
-async function handlePtyUpgrade(ctx, paths, req, socket, head) {
+async function handlePtyUpgrade(ctx, paths, req, socket, head, runtime = defaultPtyRuntime) {
+  if (!runtime.active) {
+    denyUpgrade(socket, 403)
+    return
+  }
   if (!isWebSocketUpgrade(req)) {
     try { socket.write('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch {}
     socket.destroy()
@@ -567,22 +606,30 @@ async function handlePtyUpgrade(ctx, paths, req, socket, head) {
   }
   const ws = acceptWebSocket(req, socket, head)
   if (!ws) return
+  const generation = runtime.generation
   let session = null
   let opening = false
   let cleaned = false
   let paused = false
+  let shutdown = null
   const keepalive = setInterval(() => ws.ping(), 25_000)
   keepalive.unref?.()
   const cleanup = () => {
     if (cleaned) return
     cleaned = true
     clearInterval(keepalive)
+    if (shutdown) runtime.upgrades.delete(shutdown)
     if (session) {
       ptySessions.delete(session)
       try { session.close() } catch {}
       session = null
     }
   }
+  shutdown = () => {
+    cleanup()
+    try { ws.close(1001) } catch {}
+  }
+  runtime.upgrades.add(shutdown)
   ws.on('close', cleanup)
   socket.on('drain', () => {
     if (!paused || !session) return
@@ -599,7 +646,7 @@ async function handlePtyUpgrade(ctx, paths, req, socket, head) {
     }
     if (!message || typeof message.type !== 'string' || cleaned) return
     if (!session) {
-      if (message.type !== 'open' || opening) return
+      if (message.type !== 'open' || opening || !runtime.active) return
       opening = true
       ptyOpening += 1
       try {
@@ -610,8 +657,9 @@ async function handlePtyUpgrade(ctx, paths, req, socket, head) {
         const rows = boundedInteger(message.rows, 5, 300, 32)
         const host = await findHost(paths, alias)
         const password = await requirePassword(paths, host)
+        if (!isPtyRuntimeActive(runtime, generation)) throw new Error('Terminal runtime is not active')
         session = await openPty(host, password, { cols, rows })
-        if (cleaned) {
+        if (cleaned || !isPtyRuntimeActive(runtime, generation)) {
           try { session.close() } catch {}
           session = null
           return
@@ -714,7 +762,7 @@ function registerAssetRoutes(ctx) {
   }
 }
 
-export const __test = { resolveSshPaths, listSshHosts, saveSshHost, deleteSshHost, runAction, managerTool, MAX_BODY_BYTES, PTY_ROUTE, PTY_EVENTS_ROUTE, PTY_OPEN_ROUTE, PTY_ATTACH_ROUTE, PTY_INPUT_ROUTE, PTY_RESIZE_ROUTE, PTY_CLOSE_ROUTE, MAX_PTY_SESSIONS, PTY_BUFFER_BYTES, ASSETS, handlePtyUpgrade, ptyTextSessions }
+export const __test = { resolveSshPaths, listSshHosts, saveSshHost, deleteSshHost, runAction, managerTool, MAX_BODY_BYTES, PTY_ROUTE, PTY_EVENTS_ROUTE, PTY_OPEN_ROUTE, PTY_ATTACH_ROUTE, PTY_INPUT_ROUTE, PTY_RESIZE_ROUTE, PTY_CLOSE_ROUTE, PTY_CLEAR_ROUTE, MAX_PTY_SESSIONS, PTY_BUFFER_BYTES, ASSETS, handlePtyUpgrade, ptyTextSessions }
 
 export const inject = ['webServer']
 
@@ -723,6 +771,7 @@ export function apply(ctx) {
     throw new Error('dsh-ssh-manage requires DeepSeek Harness >=0.2.1-rc.3: ctx.webServer.register is unavailable.')
   }
   const paths = resolveSshPaths(process.env)
+  const runtime = createPtyRuntime()
   ctx.effect(
     () =>
       ctx.webServer.register({
@@ -772,7 +821,7 @@ export function apply(ctx) {
       }),
     'dsh-ssh-manage: action route',
   )
-  registerPtyHttpRoutes(ctx, paths)
+  registerPtyHttpRoutes(ctx, paths, runtime)
   registerAssetRoutes(ctx)
   if (typeof ctx.webServer.tapIndex === 'function') {
     const tags = [
@@ -793,7 +842,7 @@ export function apply(ctx) {
       ctx.webServer.registerUpgrade({
         path: PTY_ROUTE,
         handler: (req, socket, head) => {
-          void handlePtyUpgrade(ctx, paths, req, socket, head).catch(() => {
+          void handlePtyUpgrade(ctx, paths, req, socket, head, runtime).catch(() => {
             try { socket.destroy() } catch {}
           })
         },
@@ -802,6 +851,12 @@ export function apply(ctx) {
   )
   ctx.effect(
     () => () => {
+      runtime.active = false
+      runtime.generation += 1
+      for (const shutdown of [...runtime.upgrades]) {
+        try { shutdown() } catch {}
+      }
+      runtime.upgrades.clear()
       clearInterval(ptyIdleTimer)
       for (const session of ptySessions) {
         try { session.close() } catch {}

package/lib/metadata.js

@@ -1,5 +1,4 @@
-import * as fs from 'node:fs/promises'
-import { atomicWriteFile, readJson, storagePaths } from './storage.js'
+import { atomicWriteFile, readJson, storagePaths, withStoreLock } from './storage.js'
 
 function clean(value, max = 80) {
   return String(value ?? '').trim().slice(0, max)
@@ -27,7 +26,12 @@ function normalizeEntry(alias, input = {}) {
   }
 }
 
-export async function loadMetadata(paths) {
+function metadataLockKey(paths) {
+  return `metadata:${storagePaths(paths).stateDir}`
+}
+
+/** Read the metadata store without taking the store lock; mutators hold it. */
+async function loadMetadataUnlocked(paths) {
   const resolved = storagePaths(paths)
   const value = await readJson(resolved.metadataPath, {})
   if (!value || typeof value !== 'object' || Array.isArray(value)) return { paths: resolved, entries: {} }
@@ -35,24 +39,37 @@ export async function loadMetadata(paths) {
   return { paths: resolved, entries }
 }
 
-export async function saveMetadata(paths, entries) {
+/** Write the metadata store without taking the store lock; mutators hold it. */
+async function saveMetadataUnlocked(paths, entries) {
   const resolved = storagePaths(paths)
   const normalized = Object.fromEntries(Object.entries(entries || {}).map(([alias, data]) => [alias, normalizeEntry(alias, data)]))
   await atomicWriteFile(resolved.metadataPath, `${JSON.stringify(normalized, null, 2)}\n`, 0o600)
   return { saved: true }
 }
 
+export async function loadMetadata(paths) {
+  return loadMetadataUnlocked(paths)
+}
+
+export async function saveMetadata(paths, entries) {
+  return withStoreLock(metadataLockKey(paths), () => saveMetadataUnlocked(paths, entries))
+}
+
 export async function updateMetadata(paths, alias, data) {
-  const current = await loadMetadata(paths)
-  current.entries[alias] = normalizeEntry(alias, { ...current.entries[alias], ...data })
-  await saveMetadata(current.paths, current.entries)
-  return current.entries[alias]
+  return withStoreLock(metadataLockKey(paths), async () => {
+    const current = await loadMetadataUnlocked(paths)
+    current.entries[alias] = normalizeEntry(alias, { ...current.entries[alias], ...data })
+    await saveMetadataUnlocked(current.paths, current.entries)
+    return current.entries[alias]
+  })
 }
 
 export async function deleteMetadata(paths, alias) {
-  const current = await loadMetadata(paths)
-  delete current.entries[alias]
-  await saveMetadata(current.paths, current.entries)
+  return withStoreLock(metadataLockKey(paths), async () => {
+    const current = await loadMetadataUnlocked(paths)
+    delete current.entries[alias]
+    await saveMetadataUnlocked(current.paths, current.entries)
+  })
 }
 
 export const __test = { normalizeEntry }

package/lib/ssh-config.js

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto'
 import * as fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
+import { withStoreLock } from './storage.js'
 
 const HOST_RE = /^[A-Za-z0-9][A-Za-z0-9_.@-]{0,63}$/
 const OPTION_NAMES = new Map([
@@ -246,13 +247,15 @@ export async function listSshHosts(paths = resolveSshPaths()) {
   return { configPath: paths.configPath, hosts: parsed.hosts, exists: text.length > 0 }
 }
 
-export async function saveSshHost({ paths = resolveSshPaths(), host, originalHost } = {}) {
+async function saveSshHostUnlocked({ paths, host, originalHost }) {
   const nextHost = validateHost(host)
   const aliasesProvided = Array.isArray(host?.aliases) && host.aliases.filter(Boolean).length > 0
   const previous = originalHost ? String(originalHost).trim() : null
+  if (previous !== null && (!HOST_RE.test(previous) || isWildPattern(previous))) throw new Error('Invalid SSH host alias')
   const text = await readConfig(paths)
   const parsed = parseSshConfig(text)
   const block = previous ? blockForHost(parsed, previous) : null
+  if (previous !== null && !block) throw new Error(`SSH host "${previous}" was not found`)
   const collision = blockForHost(parsed, nextHost.host)
   if (collision && (!block || collision.start !== block.start)) throw new Error(`SSH host "${nextHost.host}" already exists`)
   let lines = parsed.lines
@@ -274,7 +277,12 @@ export async function saveSshHost({ paths = resolveSshPaths(), host, originalHos
   return { saved: true, host: nextHost, backup }
 }
 
-export async function deleteSshHost({ paths = resolveSshPaths(), host } = {}) {
+export async function saveSshHost(options = {}) {
+  const paths = options?.paths ?? resolveSshPaths()
+  return withStoreLock(`config:${paths.configPath}`, () => saveSshHostUnlocked({ ...options, paths }))
+}
+
+async function deleteSshHostUnlocked({ paths, host }) {
   const name = String(host ?? '').trim()
   if (!HOST_RE.test(name) || isWildPattern(name)) throw new Error('Invalid SSH host alias')
   const text = await readConfig(paths)
@@ -289,4 +297,9 @@ export async function deleteSshHost({ paths = resolveSshPaths(), host } = {}) {
   return { removed: true, backup }
 }
 
+export async function deleteSshHost(options = {}) {
+  const paths = options?.paths ?? resolveSshPaths()
+  return withStoreLock(`config:${paths.configPath}`, () => deleteSshHostUnlocked({ ...options, paths }))
+}
+
 export const __test = { patchHostBlock }

package/lib/storage.js

@@ -3,6 +3,8 @@ import * as fs from 'node:fs/promises'
 import path from 'node:path'
 
 const KEY_BYTES = 32
+const storeLocks = new Map()
+const keyCreations = new Map()
 
 export function storagePaths(paths = {}) {
   const stateDir = paths.stateDir || path.join(paths.home || process.env.HOME || process.cwd(), '.dsh', '.ssh-manager')
@@ -15,6 +17,23 @@ export function storagePaths(paths = {}) {
   }
 }
 
+/**
+ * Serialize one async read-modify-write sequence per store key. Callers must
+ * only take the lock around their own read/write pair; the unlocked helpers in
+ * the vault, metadata and SSH config modules exist so nested locks never wait
+ * on themselves.
+ */
+export function withStoreLock(key, fn) {
+  const previous = storeLocks.get(key) ?? Promise.resolve()
+  const next = previous.then(() => fn())
+  const tail = next.then(() => undefined, () => undefined)
+  storeLocks.set(key, tail)
+  void tail.then(() => {
+    if (storeLocks.get(key) === tail) storeLocks.delete(key)
+  })
+  return next
+}
+
 export async function atomicWriteFile(filePath, data, mode = 0o600) {
   await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 })
   const temporary = `${filePath}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`
@@ -28,23 +47,51 @@ export async function atomicWriteFile(filePath, data, mode = 0o600) {
   }
 }
 
+function decodeKey(raw) {
+  if (Buffer.isBuffer(raw) && raw.length === KEY_BYTES) return raw
+  const decoded = Buffer.from(String(raw).trim(), 'base64')
+  if (decoded.length !== KEY_BYTES) throw new Error('SSH manager key has an invalid length')
+  return decoded
+}
+
+async function readKey(keyPath) {
+  const raw = await fs.readFile(keyPath)
+  await fs.chmod(keyPath, 0o600).catch(() => {})
+  return decodeKey(raw)
+}
+
+/** Create the key exactly once per path in this process; adopt another writer's key on EEXIST. */
+function createKeyOnce(keyPath) {
+  const pending = keyCreations.get(keyPath)
+  if (pending) return pending
+  const creation = (async () => {
+    const key = randomBytes(KEY_BYTES)
+    await fs.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 })
+    try {
+      await fs.writeFile(keyPath, key.toString('base64'), { encoding: 'utf8', mode: 0o600, flag: 'wx' })
+      return key
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      // Another process created the key first: never overwrite an existing key.
+      return await readKey(keyPath)
+    }
+  })()
+  keyCreations.set(keyPath, creation)
+  const forget = () => {
+    if (keyCreations.get(keyPath) === creation) keyCreations.delete(keyPath)
+  }
+  void creation.then(forget, forget)
+  return creation
+}
+
 export async function loadOrCreateKey(paths) {
   const resolved = storagePaths(paths)
   try {
-    const raw = await fs.readFile(resolved.keyPath)
-    await fs.chmod(resolved.keyPath, 0o600).catch(() => {})
-    if (raw.length === KEY_BYTES) return raw
-    const decoded = Buffer.from(raw.toString('utf8').trim(), 'base64')
-    if (decoded.length !== KEY_BYTES) throw new Error('SSH manager key has an invalid length')
-    return decoded
+    return await readKey(resolved.keyPath)
   } catch (error) {
     if (error?.code !== 'ENOENT') throw error
-    const key = randomBytes(KEY_BYTES)
-    await atomicWriteFile(resolved.keyPath, key.toString('base64'), 0o600)
-    // The base64 representation is easier to inspect safely while retaining 256 bits.
-    const encoded = await fs.readFile(resolved.keyPath, 'utf8')
-    return Buffer.from(encoded.trim(), 'base64')
   }
+  return createKeyOnce(resolved.keyPath)
 }
 
 export async function readJson(filePath, fallback) {

package/lib/vault.js

@@ -1,5 +1,5 @@
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
-import { atomicWriteFile, loadOrCreateKey, readJson, storagePaths } from './storage.js'
+import { atomicWriteFile, loadOrCreateKey, readJson, storagePaths, withStoreLock } from './storage.js'
 
 const ALGORITHM = 'aes-256-gcm'
 const IV_BYTES = 12
@@ -41,7 +41,8 @@ export function decryptRecords(payload, key) {
   }
 }
 
-export async function loadVault(paths) {
+/** Read the vault without taking the store lock; callers that mutate must hold it. */
+async function loadVaultUnlocked(paths) {
   const resolved = storagePaths(paths)
   const key = await loadOrCreateKey(resolved)
   const payload = await readJson(resolved.vaultPath, null)
@@ -49,7 +50,8 @@ export async function loadVault(paths) {
   return { paths: resolved, key, records }
 }
 
-export async function saveVault(paths, records) {
+/** Write the vault without taking the store lock; callers that read-modify-write must hold it. */
+async function saveVaultUnlocked(paths, records) {
   const resolved = storagePaths(paths)
   const key = await loadOrCreateKey(resolved)
   const payload = encryptRecords(normalizeRecords(records), key)
@@ -57,22 +59,38 @@ export async function saveVault(paths, records) {
   return { saved: true }
 }
 
+function vaultLockKey(paths) {
+  return `vault:${storagePaths(paths).stateDir}`
+}
+
+export async function loadVault(paths) {
+  return loadVaultUnlocked(paths)
+}
+
+export async function saveVault(paths, records) {
+  return withStoreLock(vaultLockKey(paths), () => saveVaultUnlocked(paths, records))
+}
+
 export async function setPassword(paths, alias, password) {
   const key = assertAlias(alias)
   if (typeof password !== 'string' || password.length === 0) throw new Error('Password is required')
-  const vault = await loadVault(paths)
-  vault.records[key] = password
-  await saveVault(vault.paths, vault.records)
-  return { saved: true, host: key }
+  return withStoreLock(vaultLockKey(paths), async () => {
+    const vault = await loadVaultUnlocked(paths)
+    vault.records[key] = password
+    await saveVaultUnlocked(vault.paths, vault.records)
+    return { saved: true, host: key }
+  })
 }
 
 export async function removePassword(paths, alias) {
   const key = assertAlias(alias)
-  const vault = await loadVault(paths)
-  const removed = Object.prototype.hasOwnProperty.call(vault.records, key)
-  delete vault.records[key]
-  if (removed) await saveVault(vault.paths, vault.records)
-  return { removed }
+  return withStoreLock(vaultLockKey(paths), async () => {
+    const vault = await loadVaultUnlocked(paths)
+    const removed = Object.prototype.hasOwnProperty.call(vault.records, key)
+    delete vault.records[key]
+    if (removed) await saveVaultUnlocked(vault.paths, vault.records)
+    return { removed }
+  })
 }
 
 export async function hasPassword(paths, alias) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ssh-manage",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A DSH sidebar plugin for managing SSH host profiles with a real interactive PTY terminal.",
   "license": "MIT",
   "private": false,