dsh-remote 0.8.51 → 0.8.52

package/README.en.md

@@ -285,6 +285,13 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 **`@` lists remote files but the built-in read tool cannot open them** — the harness's own file tools see the **local mirror**, which stays empty until `rw_sync` downloads it. Read remote files with `rw_read_file` or the sidebar remote tab.
 
 **A file link in a remote Session does not open** (issue #55) — fixed. When a link is clicked the harness turns it into `dsh-resource://file/session/<session>/<path>` and hands it to the built-in text preview, which reads the **local** filesystem; a remote Session's cwd is a **local mirror directory** (empty until `rw_sync`), so the open simply failed. The plugin now registers a higher-priority handler for that address and opens it over SFTP through the same editor as the sidebar "Remote Files" tab. The safety rule is deliberately conservative: it takes over only when the Session's cwd is **provably inside a mirror** and the mirror registry has loaded, so local Sessions — and the instant right after a page load — keep the built-in preview and no local file is ever mistaken for a remote one. The two cases that still cannot be mapped say so instead of showing a blank page: an address with no mirror mapping, and a Session whose workspace is not a remote mirror directory.
+Two exceptions (0.8.52+): `.md`/`.markdown` links are **not** taken over and stay with the built-in Markdown renderer (issue #64 — the remote editor would only show source, a net loss for Markdown; it reads the local mirror copy, so `rw_sync` first for the latest content). And images never had a renderer on either path anyway: the sidebar remote tree now renders png/jpg/gif/webp/svg/bmp inline (issue #66; files over 2MB fall back to the download button).
+
+**One SFTP timeout wedged every SFTP tool on that machine** (issue #65) — fixed (0.8.52+). A single operation hitting the 20s timeout used to poison the whole process for that machine (every later SFTP call paid its own 20s, while `rw_exec` stayed fine) until a disconnect/reconnect. Now a timeout kills the channel so later requests fail fast; the native backend tears the connection down and re-handshakes after two consecutive timeouts, and the openssh backend rebuilds its sftp child — a transient network blip no longer ends with "disconnect and reconnect". As a bonus, `rw_edit` now writes atomically (temp file + rename), so an interrupted write can no longer truncate the remote file to zero bytes, and the original permission bits are preserved.
+
+**The machine's IP / username changed — must every workspace be recreated?** (issue #67) — no (0.8.52+). Edit the machine's new address on the settings page and save, or call `rw_connect(machineId=…, host=…, username=…, port=…)` with the new address: every workspace mirror bound to that machine is **rebound in place** (its `.dsh-remote-meta.json` is rewritten) — local content is kept, no re-sync needed, and the save response says how many mirrors were rebound. The mirror directory name does not follow (live Sessions hold cwd paths inside it); the name is a display label only and does not affect connectivity.
+
+**Remote Sessions could not see the workspace AGENTS.md** (issue #68) — fixed (0.8.52+). The core instruction loader only knows the local filesystem, and a remote Session's cwd is the local mirror, so the remote repo's AGENTS.md never reached the model's context. Now, when `rw_pick_workspace` succeeds, the remote workspace gets a shallow scan (root + at most two levels down, matching `AGENTS.md`/`CLAUDE.md` only); the found files are synced into the local mirror under a three-way guard (root-level copies thus enter the core's own injection path, exactly like a local Session), and an index of paths + headings is rendered into the system prompt, telling the model to read nested instruction files with `rw_read_file` before editing. Full-tree recursion and plugin-side full-text injection are deliberately **not** done (the former would scan through multi-project roots; the latter would run a second injection pipeline in parallel with the core's).
 
 **The terminal in a remote Session is still the local one** (issue #55) — that is **by design, and a plugin cannot change it**, but there is an equivalent: DSH's sidebar terminal is core, its PTY comes from the **context-global** `subprocess` service, and its cwd is the Session's own workspace directory (the local mirror for a remote Session). A plugin can neither replace that service nor retarget the core terminal onto SSH. For a **genuine remote terminal** use the "Remote DSH Web UI" (above): it opens the **remote machine's own** DSH in this browser, and that interface's terminal runs on the remote host, with no extra configuration. To run a single remote command instead, use `rw_exec` (add `pty: true` for an interactive PTY).
 

package/README.md

@@ -274,6 +274,27 @@ scripts/dev-run.sh --status    # 是否在运行
 本地会话与页面刚加载的那一瞬间仍然走内置预览 —— 不会把本地文件误当成远程文件。
 两个仍然开不了的情况会给出明确提示而不是空白页：链接指向的是**绝对**远端路径之外无法映射的地址，
 或该会话的工作区不是一个远程镜像目录。
+两个例外（0.8.52+）：`.md`/`.markdown` 链接**不被接管**、交还内置 Markdown 渲染（issue #64——远程编辑器只能看
+源码，对 Markdown 是净损失；它读本地镜像副本，要最新内容先 `rw_sync`）；图片文件则在内置链路与远程链路
+都谈不上「渲染」，侧栏远程文件树现在直接内联显示 png/jpg/gif/webp/svg/bmp（issue #66，>2MB 退回下载按钮）。
+
+**SFTP 操作一旦超时就永远卡死**（issue #65）—— 已修（0.8.52+）。旧版里一次撞满 20s 超时的 SFTP 操作会把
+该机器在本进程内的全部 SFTP 工具拖到永久超时（`rw_exec` 却正常），只能断连重连。现在超时即置死该通道、
+后续请求立即失败；native 后端连续两次超时会废弃整条连接重新握手，openssh 后端会重建 sftp 子进程——
+一次网络抖动不再需要用「断开重连」来收场。顺带，`rw_edit` 改成了「临时文件 + rename」原子写，
+写一半超时不会再把远端文件截成 0 字节，原文件的权限位也会保留。
+
+**机器换了 IP / 用户名，工作区要全部重建吗？**（issue #67）—— 不用（0.8.52+）。在设置页编辑该机器的新
+地址并保存，或 `rw_connect(machineId=…, host=…, username=…, port=…)` 同传新地址：该机器名下所有工作区
+镜像会**原地重绑**（改写镜像的 `.dsh-remote-meta.json`），本地内容保留、无需重新同步，保存后会提示重绑了
+几个镜像。镜像目录名不会跟着改（活 session 的 cwd 在其中），目录名只是显示标签、不影响连接。
+
+**远程会话看不到工作区的 AGENTS.md**（issue #68）—— 已修（0.8.52+）。核心的指令加载只认本地文件系统，
+而远程会话的 cwd 是本地镜像，远端仓库的 AGENTS.md 以前永远进不了模型上下文。现在 `rw_pick_workspace`
+成功时会对远程工作区做浅扫（根 + 向下 ≤2 层，只匹配 `AGENTS.md`/`CLAUDE.md`），把命中的文件按三向安全
+规则同步进本地镜像（根级文件由此进入核心自己的注入链路，与本地会话一致），并把路径+标题索引渲染进
+system prompt，提示模型编辑前用 `rw_read_file` 阅读嵌套层的指令。全树递归扫描与插件侧全文注入都**刻意
+不做**（前者会扫穿多项目根目录，后者会与核心的注入管线并行打架）。
 
 **远程会话里的终端还是本机的**（issue #55）—— 这是**设计如此，插件改不了**，但有等效方案。
 DSH 的侧栏终端是核心功能：它的 PTY 来自**全局唯一**的 `subprocess` 服务，cwd 取会话自己的

package/lib/client.js

@@ -179,6 +179,7 @@ window.__ModuleLoader__.load({
         'settings.feedback': '💬 反馈建议 / 提 issue',
         'settings.deleted': '已删除',
         'settings.saved': '已保存更新',
+        'settings.rebound': '已将 {n} 个本地工作区镜像重新绑定到新地址（内容保留，无需重新同步）',
         'settings.added': '已添加 — 可设为当前',
         'settings.secretStoreFailed': '密码未能写入系统密钥库（{msg}），已回退为明文保存在 machines.json，连接仍可用。',
         'settings.switched': '已切换为当前远程机',
@@ -467,6 +468,7 @@ window.__ModuleLoader__.load({
         'settings.feedback': '💬 Feedback / report issue',
         'settings.deleted': 'Deleted',
         'settings.saved': 'Saved',
+        'settings.rebound': 'Rebound {n} local workspace mirror(s) to the new address (content kept — no re-sync needed)',
         'settings.added': 'Added — you can set it as current',
         'settings.secretStoreFailed': 'The OS keychain refused the password ({msg}); it was saved as plaintext in machines.json and the machine still connects.',
         'settings.switched': 'Switched to current remote machine',
@@ -1190,6 +1192,9 @@ window.__ModuleLoader__.load({
           // Issue #30: "加密保存密码"失败时服务端回退明文并带警告 —— 不能再静默
           // 保存一台没有凭据的机器（那会让之后每次连接都失败且没有原因）。
           if (r && r.warning === 'secret-store-failed') setErr(tr('settings.secretStoreFailed', { msg: r.warningDetail || 'unknown' }))
+          // Issue #67: an edited address rebinds the machine's existing mirrors —
+          // say so, or the user cannot tell their workspaces came along.
+          else if (r && r.reboundMirrors) setMsg(tr('settings.saved') + ' — ' + tr('settings.rebound', { n: r.reboundMirrors }))
           else setMsg(form.id ? tr('settings.saved') : tr('settings.added'))
         }).catch((e) => setErr(String((e && e.message) || e))).finally(() => setBusy(false))
       }
@@ -3237,7 +3242,7 @@ window.__ModuleLoader__.load({
       React.useEffect(load, [path])
 
       const startEdit = () => {
-        if (!data || data.binary) return
+        if (!data || data.binary || data.image) return
         setDraft((data.content != null ? data.content : '').replace(/\n…\[truncated:.*$/, ''))
         setEdit(true); setErr('')
       }
@@ -3276,7 +3281,7 @@ window.__ModuleLoader__.load({
                 React.createElement('button', { type: 'button', className: 'dsh-rw-btn dsh-rw-primary', style: { ...primaryBtnS, padding: '2px 10px', fontSize: 12 }, onClick: saveRemote, disabled: saving || !dirty, title: tr('file.saveHint') }, saving ? tr('file.saving') : tr('file.saveToRemote')),
                 React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: () => { setEdit(false); setErr('') } }, tr('file.cancel')))
             : React.createElement(React.Fragment, null,
-                React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: startEdit, disabled: !data || data.binary }, tr('file.edit')),
+                React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: startEdit, disabled: !data || data.binary || data.image }, tr('file.edit')),
                 React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: downloadMirror, disabled: saving }, tr('file.download'))),
         ),
         React.createElement('div', { style: { flex: 1, overflow: 'auto', minHeight: 0, display: 'flex', flexDirection: 'column' } },
@@ -3285,7 +3290,10 @@ window.__ModuleLoader__.load({
             : (data && data.binary
                   ? React.createElement('div', { style: { padding: 12, fontSize: 13, color: T.warn } },
                       tr('file.binary', { size: (data.size != null ? data.size + ' bytes' : tr('file.unknownSize')) }))
-                  : (edit
+                  : data && data.image
+                    ? React.createElement('div', { style: { flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 12, minHeight: 0 } },
+                        React.createElement('img', { src: `data:${data.mime};base64,${data.content}`, alt: baseName, style: { maxWidth: '100%', maxHeight: '100%', objectFit: 'contain' } }))
+                    : (edit
                       ? React.createElement('textarea', {
                           value: draft,
                           onChange: (e) => setDraft(e.target.value),
@@ -3636,6 +3644,10 @@ window.__ModuleLoader__.load({
             canOpen: (address) => {
               const parsed = parseCoreFileAddress(address)
               if (!parsed) return false
+              // Let the built-in Markdown preview keep .md/.markdown files: it can
+              // render them, whereas the remote-link editor would only show source.
+              const name = String(parsed.path || '').split(/[\\/]/).pop()
+              if (/\.(md|markdown)$/i.test(name)) return false
               const cwd = sessionCwdFor(parsed.sessionId)
               // `MIRRORS.loaded` is checked so a cold start NEVER steals a local
               // link: an empty registry cannot prove a mirror, and guessing would

package/lib/index.js

@@ -38,6 +38,7 @@ import { importableEntries, sshConfigPath, readSshConfigText, resolveMachineSshC
 import { createRemoteFileReference, installFileReferenceOverlay, DEFAULT_EXCLUDED_DIRECTORIES } from './file-reference.js'
 import { getSecret, deleteSecret, platformBackend, persistPassword } from './credential.js'
 import { syncTree, pushTree, loadSyncState, saveSyncState, pushOneFile } from './sync.js'
+import { createInstructionIndex, formatInstructionIndex } from './instructions.js'
 import { searchRemote } from './search.js'
 import { installTerminalShell } from './remote-shell.js'
 import { resolveMirror, poolKey, lookupSessionCwd, encodeSegmentSafe, readSessionHeaderCwd, requestSessionHint } from './binding.js'
@@ -1124,6 +1125,14 @@ export async function apply(ctx, config) {
     autoPushWatchers.clear()
   }, 'dsh-remote.autopush')
 
+  // ── remote instruction-file index (issue #68) ────────────────────────────
+  // The core AGENTS.md loader only sees the LOCAL mirror, so a remote repo's
+  // instruction files never reach the model's context. This index shallow-
+  // scans a bound workspace (root + ≤2 levels, AGENTS.md / CLAUDE.md only),
+  // mirrors the finds into the local mirror (where the core loader looks),
+  // and lists them in the system-prompt section below. See lib/instructions.js.
+  const instructionIndex = createInstructionIndex()
+
   // Helpers shared by session-bound tools and the machine-scoped web routes take
   // the pool explicitly (`p`), defaulting to the active-machine pool so route
   // callers — which are machine-scoped by design — stay unchanged.
@@ -1225,6 +1234,106 @@ export async function apply(ctx, config) {
     }
     return out
   }
+
+  /**
+   * Rebind every mirror recorded for one machine identity to a NEW identity
+   * (issue #67): when a machine's IP/user/port changes, its workspaces must
+   * follow instead of being recreated. The mirror's `.dsh-remote-meta.json` is
+   * the authoritative binding — session routing (bindingFor), pool keying
+   * (poolForMachine) and the sidebar badges all read identity FROM THE META,
+   * not from the directory name — so rewriting the meta re-points every live
+   * session at the new address while the local mirror content stays put.
+   *
+   * The host directory itself is deliberately NOT renamed: live sessions hold
+   * cwd paths inside it, and a rename would dangle them into "session is
+   * LOCAL" refusals (on Windows the rename usually fails outright while a
+   * shell sits inside). The directory name is a display label only; a stale
+   * label after a rebind is the documented cost of keeping sessions alive.
+   *
+   * Matching covers both machine kinds: an ALIAS machine's mirrors are found
+   * through the recorded `alias` (their meta host is the resolved address at
+   * creation time), a literal machine's through host+port+username.
+   *
+   * @param {object} prev - the machine record BEFORE the identity change.
+   * @param {object} next - the machine record AFTER it.
+   * @returns {number} how many mirrors were rebound.
+   */
+  const rebindMirrors = (prev, next) => {
+    if (!prev || !next) return 0
+    const prevAlias = aliasOf(prev)
+    const prevId = identityOf(prev)
+    const prevRaw = { host: String(prev.host || ''), port: Number(prev.port) || 22, username: String(prev.username || '') }
+    const nextAlias = aliasOf(next)
+    const nextEff = withSshConfig(next) || next
+    const nextId = {
+      host: String(nextEff.host || next.host || ''),
+      port: Number(nextEff.port || next.port) || 22,
+      username: String(nextEff.username || next.username || ''),
+    }
+    const nextRaw = { host: String(next.host || ''), port: Number(next.port) || 22, username: String(next.username || '') }
+    const sameIdentity = (a, b) => a.host === b.host && a.port === b.port && a.username === b.username
+    if (!prevAlias && sameIdentity(prevId, nextId) && sameIdentity(prevRaw, nextRaw)) return 0
+    if (prevAlias && prevAlias === nextAlias) return 0
+    const root = remoteWorkspacesRoot()
+    let rebound = 0
+    let hostDirs = []
+    try { hostDirs = readdirSync(root) } catch { return 0 }
+    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 metaPath = path.join(hostPath, entry, '.dsh-remote-meta.json')
+        let meta = null
+        try { meta = JSON.parse(readFileSync(metaPath, 'utf8')) } catch { continue }
+        if (!meta || !meta.host) continue
+        const byAlias = prevAlias && String(meta.alias || '') === prevAlias
+        // A meta records the RESOLVED identity at pick time, but that identity
+        // can also have been written raw — match on either form of the old
+        // identity so a rebind still finds mirrors recorded before a later
+        // ssh-config resolution rewrote what "this machine" meant.
+        const metaId = { host: String(meta.host), port: Number(meta.port) || 22, username: String(meta.username || '') }
+        const byIdentity = sameIdentity(metaId, prevId) || sameIdentity(metaId, prevRaw)
+        if (!byAlias && !byIdentity) continue
+        const updated = { ...meta }
+        if (nextAlias) {
+          // Alias machine: the recorded alias is what future resolution keys
+          // on; the resolved address refreshes only when it actually resolved
+          // (an unmatched alias keeps the old literal values rather than
+          // stamping the alias NAME into the address fields).
+          updated.alias = nextAlias
+          if (nextEff.sshConfigMatched || nextEff.sshAlias) {
+            updated.host = nextId.host
+            updated.port = nextId.port
+            updated.username = nextId.username
+          }
+        } else {
+          delete updated.alias
+          updated.host = nextRaw.host
+          updated.port = nextRaw.port
+          updated.username = nextRaw.username
+        }
+        updated.reboundAt = new Date().toISOString()
+        try {
+          writeFileSync(metaPath, JSON.stringify(updated, null, 2))
+          rebound++
+        } catch { /* leave that mirror as-is */ }
+      }
+    }
+    if (rebound) {
+      // The old identity's pooled connection dials an address the user just
+      // abandoned: drop it so nothing keeps a dead SSH session warm. The new
+      // identity gets its pool lazily on the next tool call.
+      const stale = machinePools.get(poolKey(prevId))
+      if (stale) {
+        machinePools.delete(poolKey(prevId))
+        try { stale.close() } catch { /* already gone */ }
+      }
+    }
+    return rebound
+  }
+
   if (config.autoPush && wsPath()) {
     startAutoPush(mirrorDirFor(wsPath(), config.host, config.username, config.port))
   }
@@ -1614,10 +1723,10 @@ 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, 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.',
+        '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. Rebinding (issue #67): pass machineId TOGETHER with a new host/username/port to update that saved machine in place — every workspace mirror bound to its old address is re-pointed (local content kept, no re-sync) instead of forcing new workspaces.',
       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.' },
+        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 — EXCEPT for rebinding (issue #67): combine machineId with a new host/username/port to update the machine in place and re-point its existing workspace mirrors.' },
         username: { type: 'string', description: 'SSH user (default from config or root)' },
         port: { type: 'integer', description: 'SSH port (default 22)' },
         password: { type: 'string', description: 'SSH password (prefer SSH key when possible)' },
@@ -1634,6 +1743,9 @@ export async function apply(ctx, config) {
       },
       output: textOut,
       async execute(args) {
+        // Issue #67: set by the machineId+overrides path, prepended to the
+        // success line so the rebind is visible in the tool result.
+        let reboundNote = ''
         const mid = String(args.machineId || '').trim()
         if (mid) {
           // Connect with an ALREADY SAVED machine (issue #48): the registry
@@ -1641,6 +1753,25 @@ export async function apply(ctx, config) {
           // keychain-backed passwords, stored passphrases, proxies, aliases.
           const i = machineIndex(mid)
           if (i < 0) throw new Error(`rw_connect: no saved machine "${mid}" — list saved machines with rw_machines`)
+          // Issue #67: passing host/username/port ALONGSIDE a machineId rebinds
+          // the saved machine in place — the fix for "the IP changed, do not
+          // make me recreate every workspace". The record keeps its id (and
+          // every credential), and each mirror bound to the old identity is
+          // re-pointed so live sessions keep working against the new address.
+          const prev = machines[i]
+          const overrides = {}
+          if (args.host !== undefined && String(args.host).trim()) overrides.host = String(args.host).trim()
+          if (args.username !== undefined && String(args.username).trim()) overrides.username = String(args.username).trim()
+          if (args.port !== undefined && Number(args.port)) overrides.port = Number(args.port)
+          let rebound = 0
+          if (Object.keys(overrides).length) {
+            const next = { ...prev, ...overrides }
+            try { rebound = rebindMirrors(prev, next) } catch { /* best effort */ }
+            machines[i] = next
+          }
+          if (rebound) {
+            reboundNote = `Rebound ${rebound} workspace mirror(s) from ${prev.username}@${prev.host}:${prev.port} to the new address (local content kept — no re-sync needed).\n`
+          }
           store.currentId = machines[i].id
           ephemeral = null
           saveMachines(machines, store.currentId)
@@ -1749,7 +1880,7 @@ export async function apply(ctx, config) {
           const via = active && active.sshAlias
             ? `\n(ssh-config alias "${active.sshAlias}" → ${effUser}@${effHost}:${effPort}` + (active.sshConfigWarnings && active.sshConfigWarnings.length ? `; ${active.sshConfigWarnings.join(' ')}` : '') + ')'
             : ''
-          return { text: `Connected to ${effHost} as ${effUser}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
+          return { text: `${reboundNote}Connected to ${effHost} as ${effUser}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
         } catch (err) {
           throw new Error(friendlyMessage(err, { host: effHost, port: effPort }))
         }
@@ -1825,6 +1956,12 @@ export async function apply(ctx, config) {
         if (!b.bound) persistWorkspace(p)
         const local = ensureMirror(p, b.host, b.username, b.port, { alias: b.alias || "" })
         startAutoPush(local)
+        // Issue #68: discover the workspace's AGENTS.md / CLAUDE.md NOW — the
+        // first prompt assembly can come before any rw_sync, and the mirror
+        // copy must already be in place for the core instruction loader to
+        // pick it up. Awaited (the scan is a handful of shallow readdirs) but
+        // fully best-effort: a scan failure never fails the pick.
+        try { await instructionIndex.refresh({ pool: b.pool, ws: p, mirrorDir: local, force: true }) } catch { /* best effort */ }
         // The closing hint depends on where THIS session stands (issue #63):
         // in a LOCAL session "Run rw_sync" is a dead instruction — rw_sync
         // refuses a local session — so say the mirror must be OPENED first.
@@ -1878,11 +2015,21 @@ export async function apply(ctx, config) {
           }
           return { text }
         }
+        // Issue #68: a real sync can pull in (or obsolete) instruction files —
+        // refresh the prompt index afterwards. Kept inside the task body so a
+        // background sync refreshes when IT finishes, not when it is queued.
+        const runSyncAndIndex = async () => {
+          const r = await runSync()
+          if (!args.dryRun) {
+            try { await instructionIndex.refresh({ pool: b.pool, ws: p, mirrorDir: local, force: true }) } catch { /* best effort */ }
+          }
+          return r
+        }
         if (args.async) {
-          const t = tasks.start('sync', `sync ${p}`, runSync)
+          const t = tasks.start('sync', `sync ${p}`, runSyncAndIndex)
           return { text: `sync started in background: taskId=${t.id} (GET /dsh-remote/task?id=${t.id} for progress)` }
         }
-        return runSync()
+        return runSyncAndIndex()
       },
     }),
 
@@ -2137,7 +2284,26 @@ export async function apply(ctx, config) {
         if (st1.size !== st0.size || st1.mtime !== st0.mtime) {
           throw new Error(`rw_edit: ${p} changed on the remote while editing (conflict) — re-read and retry`)
         }
-        await sftp.writeFile(p, encodeText(out, args.encoding || config.encoding))
+        // Atomic write: stage to a temp file and rename over the target so a
+        // mid-write failure cannot truncate the original (issue #65). Same
+        // directory keeps the rename on one filesystem.
+        const tmpPath = `${p}.dsh-remote-edit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`
+        try {
+          await sftp.writeFile(tmpPath, encodeText(out, args.encoding || config.encoding))
+          // renameOverwrite, not rename: the target EXISTS by definition here,
+          // and plain SSH_FXP_RENAME refuses to replace it (issue #65).
+          await sftp.renameOverwrite(tmpPath, p)
+          // The rename swaps in a FRESH inode, so the original permission bits
+          // (an executable script's +x, a 0600 secret) would silently reset to
+          // the umask default. Restore them; a chmod failure must not fail the
+          // edit itself — the content is already safely in place.
+          if (st0 && typeof st0.mode === 'number') {
+            try { await sftp.setstat(p, { mode: st0.mode & 0o7777 }) } catch { /* best effort */ }
+          }
+        } catch (err) {
+          try { await sftp.unlink(tmpPath) } catch { /* best effort */ }
+          throw err
+        }
         audit('edit', `edit ${p} (${n} occurrence(s))`, 0, b)
         return { ok: true, bytes: Buffer.byteLength(out), text: `edited ${p}: replaced ${n} occurrence(s)` }
       },
@@ -2549,7 +2715,7 @@ export async function apply(ctx, config) {
       const session = agent && agent.session
       const cwd = session && session.header && session.header.cwd
       if (!cwd) return '' // no session cwd → nothing to map → stay quiet
-      const { remotePath, machine } = resolveMirrorForLocal(cwd)
+      const { remotePath, machine, mirrorDir } = resolveMirrorForLocal(cwd)
       if (!remotePath) return '' // this session is NOT a remote session (issue #13)
       // Name the machine the MIRROR records, not the active one: pairing this
       // session's remote path with whichever machine happens to be active
@@ -2562,6 +2728,17 @@ export async function apply(ctx, config) {
       const fwd = forwards.list().filter((f) => f.active).map((f) => `${f.direction}:127.0.0.1:${f.listenPort}→${f.targetHost}:${f.targetPort}`)
       let extra = ''
       if (fwd.length) extra = `\nActive port forwards: ${fwd.join(', ')}`
+      // Issue #68: surface the workspace's AGENTS.md / CLAUDE.md. The scan is
+      // lazy (fire-and-forget on first assembly; negative-cached on failure),
+      // so the index appears from the NEXT assembly once known — rw_pick_workspace
+      // scans eagerly, so a picked workspace normally has it from the start.
+      if (machine && mirrorDir) {
+        instructionIndex.note({ pool: poolForMachine(machine), ws: remotePath, mirrorDir })
+        const instr = instructionIndex.get(mirrorDir)
+        if (instr && instr.files && instr.files.length) {
+          extra += `\n${formatInstructionIndex(instr.files, (p) => toDisplayPath(p, platform))}`
+        }
+      }
       // Issue #39: `@` mentions are resolved from the REMOTE tree by
       // lib/file-reference.js, so the model must know they are remote-relative
       // and that the built-in read tool sees only the local mirror.
@@ -3193,6 +3370,14 @@ export async function apply(ctx, config) {
               // alone, so a fresh registry stays "no choice yet" (not an
               // explicit none) and a previously-cleared registry stays cleared.
               saveMachines(machines, store.currentId, false)
+              // Issue #67: an EDITED connection identity (host/user/port) must
+              // carry the machine's existing workspaces over — without this the
+              // mirrors stayed bound to the old address and the user had to
+              // create (and re-sync) a brand-new workspace for the new IP.
+              let reboundMirrors = 0
+              if (i >= 0 && prev) {
+                try { reboundMirrors = rebindMirrors(prev, rec) } catch { /* best effort */ }
+              }
               // Issue #50: host/user/port/key have ONE home — ~/.ssh/config.
               // Saving a literal machine upserts a marker-tagged Host block,
               // so the file and the registry can never drift; the record's
@@ -3234,6 +3419,7 @@ export async function apply(ctx, config) {
                 machine: sanitizeMachine(rec),
                 machines: machinesForClient(),
                 currentId: store.currentId,
+                ...(reboundMirrors ? { reboundMirrors } : {}),
                 ...(warning ? { warning, warningDetail } : {}),
                 ...(sshConfigWarning ? { sshConfigWarning } : {}),
               })

package/lib/instructions.js

@@ -0,0 +1,288 @@
+// dsh-remote — remote instruction-file index (issue #68).
+//
+// The core instruction loader (@deepseek-ai/dsh-agent-instructions) discovers
+// AGENTS.md through the LOCAL filesystem only: from two user-global roots plus
+// the projectRoot→cwd ancestor chain. A remote session's cwd is the local
+// MIRROR of the remote workspace, and that mirror stays empty until rw_sync —
+// so a 20 KB AGENTS.md that governs the remote repo never enters the model's
+// context, while the same file is auto-injected in a local session. File
+// ACCESS was never the problem (rw_read_file reads it fine); what is missing
+// is the model knowing it should.
+//
+// This module closes the gap on the plugin side, along the two cheapest axes
+// the issue lists (the third — a remote ctx.fs provider — belongs to core):
+//
+//   1. INDEX in the system prompt: a shallow scan of the remote workspace
+//      (root + at most two directory levels down, AGENTS.md / CLAUDE.md only)
+//      is rendered into the dsh-remote prompt section as a path list with
+//      headings, telling every new session the files exist and to read them
+//      with rw_read_file before editing that tree. This is an INDEX, not a
+//      second injection pipeline — the full text stays out of the prompt and
+//      out of any parallel baseline, exactly as the issue demands.
+//   2. MIRROR the found files into the local mirror at their relative paths
+//      (three-way safe — a local edit is never clobbered, see below). A
+//      root-level AGENTS.md then sits exactly where the CORE loader looks in
+//      a local session, so the normal baseline/incremental machinery picks it
+//      up unchanged; no plugin-side injection logic runs in parallel with it.
+//
+// Deliberate non-goals (the issue's "请不要做"):
+//   - NO unbounded recursion of the remote root (multi-project roots like
+//     /root would scan forever): the walk is depth- and count-capped.
+//   - NO full-text injection from the plugin.
+
+import { existsSync, mkdirSync, statSync, writeFileSync, utimesSync } from 'node:fs'
+import path from 'node:path'
+import { joinRemotePath, relPathUnder } from './paths.js'
+import { loadSyncState, saveSyncState } from './sync.js'
+
+/** File names treated as agent instruction files (compared case-insensitively;
+ *  the mirrored copy keeps the remote's exact casing). */
+export const INSTRUCTION_NAMES = ['agents.md', 'claude.md']
+
+/** An instruction file bigger than this is indexed (path + note) but not read. */
+export const INSTRUCTION_MAX_BYTES = 256 * 1024
+
+/** Caps that keep the shallow scan shallow. */
+export const INSTRUCTION_MAX_FILES = 20
+export const INSTRUCTION_MAX_DIRS = 60
+export const INSTRUCTION_MAX_DEPTH = 2 // 0 = workspace root, 1 = sub/, 2 = sub/sub/
+
+/** Directories that never contain a project's governing instructions. */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.svn', '.hg', 'dist', 'build', 'out',
+  '.next', '.nuxt', '.cache', '.turbo', 'coverage', 'target', 'vendor',
+])
+
+export const isInstructionName = (name) => INSTRUCTION_NAMES.includes(String(name || '').toLowerCase())
+
+/** Pull the first Markdown headings out of an instruction file, for the index. */
+export function extractHeadings(text, max = 8) {
+  const out = []
+  for (const line of String(text || '').split('\n')) {
+    const m = /^#{1,3}\s+(.+?)\s*#*\s*$/.exec(line)
+    if (!m) continue
+    out.push(m[1].slice(0, 60))
+    if (out.length >= max) break
+  }
+  return out
+}
+
+/**
+ * Shallow-scan a remote workspace for instruction files: the root directory
+ * plus up to INSTRUCTION_MAX_DEPTH levels of subdirectories, matching
+ * AGENTS.md / CLAUDE.md basenames. Bounded by INSTRUCTION_MAX_DIRS readdirs
+ * and INSTRUCTION_MAX_FILES files; anything past the caps is silently
+ * skipped (the index is a hint, not an inventory).
+ *
+ * @param {object} sftp - the promisified sftp surface (readdir/stat/readFile).
+ * @param {string} remoteRoot - absolute remote workspace path (normalized).
+ * @returns {Promise<Array<{rel: string, remote: string, size: number, mtime: number, content: Buffer|null, headings: string[]}>>}
+ *   `content`/`headings` are null/empty for files over INSTRUCTION_MAX_BYTES.
+ */
+export async function scanInstructionFiles(sftp, remoteRoot, opts = {}) {
+  const maxDepth = Math.max(0, Math.min(Number(opts.maxDepth ?? INSTRUCTION_MAX_DEPTH) || 0, 4))
+  const maxDirs = Math.max(1, Number(opts.maxDirs ?? INSTRUCTION_MAX_DIRS) || INSTRUCTION_MAX_DIRS)
+  const maxFiles = Math.max(1, Number(opts.maxFiles ?? INSTRUCTION_MAX_FILES) || INSTRUCTION_MAX_FILES)
+  const files = []
+  // Breadth-first so a wide root cannot push the walk deep before the shallow
+  // (more commonly governing) files are seen.
+  const queue = [{ dir: remoteRoot, depth: 0 }]
+  let dirsScanned = 0
+  while (queue.length && files.length < maxFiles && dirsScanned < maxDirs) {
+    const { dir, depth } = queue.shift()
+    dirsScanned++
+    let entries = []
+    try { entries = (await sftp.readdir(dir)) || [] } catch { continue }
+    for (const e of entries) {
+      const name = String(e.filename || '')
+      if (!name || name === '.' || name === '..' || name.startsWith('.')) {
+        // Hidden entries are skipped wholesale EXCEPT the names themselves
+        // never start with a dot, so nothing is lost.
+        continue
+      }
+      const isDir = !!(e.attrs && typeof e.attrs.isDirectory === 'function' && e.attrs.isDirectory())
+      const isLink = !!(e.attrs && typeof e.attrs.isSymbolicLink === 'function' && e.attrs.isSymbolicLink())
+      if (isDir) {
+        // Symlinked dirs are not followed: the walk stays inside the workspace
+        // tree and cannot loop through a link back to an ancestor.
+        if (isLink) continue
+        if (depth < maxDepth && !SKIP_DIRS.has(name.toLowerCase()) && queue.length + dirsScanned < maxDirs) {
+          queue.push({ dir: joinRemotePath(dir, name), depth: depth + 1 })
+        }
+        continue
+      }
+      if (!isInstructionName(name)) continue
+      const remote = joinRemotePath(dir, name)
+      const rel = relPathUnder(remoteRoot, remote) || name
+      let st = null
+      try { st = await sftp.stat(remote) } catch { continue }
+      const size = st && typeof st.size === 'number' ? st.size : 0
+      const mtime = st && typeof st.mtime === 'number' ? st.mtime : 0
+      let content = null
+      let headings = []
+      if (size <= INSTRUCTION_MAX_BYTES) {
+        try {
+          content = await sftp.readFile(remote)
+          headings = extractHeadings(content.toString('utf8'))
+        } catch { content = null }
+      }
+      files.push({ rel, remote, size, mtime, content, headings })
+      if (files.length >= maxFiles) break
+    }
+  }
+  return files
+}
+
+// The three-way keys mirror lib/sync.js exactly (size + whole-second mtime):
+// a file this module places into the mirror must be indistinguishable from
+// one rw_sync pulled, or the next sync would report a phantom conflict.
+const keyOf = (size, mtime) => `${size}:${Math.floor(mtime || 0)}`
+const localKeyOf = (st) => (st ? keyOf(st.size, st.mtimeMs / 1000) : null)
+
+/**
+ * Write scanned instruction files into the local mirror at their workspace-
+ * relative paths, three-way safe against `.dsh-remote-sync-state.json`:
+ *
+ *   - local missing                        → write (+ align mtime, record state)
+ *   - local identical to remote            → keep (record state if absent)
+ *   - remote changed, local untouched (L==S) → write (a plain pull)
+ *   - local edited (L!=S), remote unchanged → SKIP — a local edit is never
+ *     clobbered; rw_sync surfaces it as a conflict like any other file
+ *   - both changed / unknown local content → SKIP (rw_sync arbitrates)
+ *
+ * @returns {{written: string[], present: Set<string>}} rel paths written now,
+ *   and every rel that exists locally afterwards (for the index's "mirrored"
+ *   badge).
+ */
+export function syncInstructionsToMirror(files, mirrorDir) {
+  const written = []
+  const present = new Set()
+  if (!mirrorDir || !Array.isArray(files) || !files.length) return { written, present }
+  const state = loadSyncState(mirrorDir)
+  let stateDirty = false
+  for (const f of files) {
+    if (!f || !f.rel || !f.content) continue
+    const lp = path.join(mirrorDir, ...String(f.rel).split('/'))
+    const rk = keyOf(f.size, f.mtime)
+    const sk = state[f.rel] ? keyOf(state[f.rel].size, state[f.rel].mtime) : null
+    let lk = null
+    try { lk = existsSync(lp) ? localKeyOf(statSync(lp)) : null } catch { lk = null }
+    if (lk === rk) {
+      // Identical bytes in place already (same size AND mtime second) — only
+      // make sure the snapshot knows about it.
+      present.add(f.rel)
+      if (!sk) { state[f.rel] = { size: f.size, mtime: f.mtime }; stateDirty = true }
+      continue
+    }
+    const canWrite = lk === null || (sk !== null && rk !== sk && lk === sk)
+    if (!canWrite) continue
+    try {
+      mkdirSync(path.dirname(lp), { recursive: true })
+      writeFileSync(lp, f.content)
+      // Align the local mtime to the remote's so the next rw_sync sees
+      // L==R==S and skips the file instead of flagging a local modification.
+      try { utimesSync(lp, new Date(f.mtime * 1000), new Date(f.mtime * 1000)) } catch { /* cosmetic */ }
+      state[f.rel] = { size: f.size, mtime: f.mtime }
+      stateDirty = true
+      written.push(f.rel)
+      present.add(f.rel)
+    } catch { /* a mirror write failure must not break the index */ }
+  }
+  if (stateDirty) {
+    try { saveSyncState(mirrorDir, state) } catch { /* best effort */ }
+  }
+  return { written, present }
+}
+
+/**
+ * Render the prompt-section index of remote instruction files. Paths are
+ * shown through `display` (the platform-aware display formatter), headings
+ * give the model a content hint without injecting the full text.
+ */
+export function formatInstructionIndex(files, display = (p) => p) {
+  const lines = files.slice(0, 10).map((f) => {
+    const h = f.headings && f.headings.length ? ` (headings: ${f.headings.slice(0, 6).join(' / ')})` : ''
+    const over = f.size > INSTRUCTION_MAX_BYTES ? ` (${Math.round(f.size / 1024)} KB)` : ''
+    const mirrored = f.mirrored ? '; synced into the local mirror' : ''
+    return `- ${display(f.remote)}${h}${over}${mirrored}`
+  })
+  return (
+    'Remote instruction files found in this workspace (they govern how to work in their directories; '
+    + 'root-level copies were synced into the local mirror, but nested ones are NOT auto-injected — '
+    + 'read them with rw_read_file before editing that tree):\n'
+    + lines.join('\n')
+  )
+}
+
+/**
+ * Per-process index of remote instruction scans, keyed by mirror directory.
+ * Deduplicates in-flight scans, negative-caches failures for a minute (an
+ * offline machine must not turn every prompt assembly into a connect
+ * attempt), and never throws — the index is strictly best-effort.
+ */
+export function createInstructionIndex() {
+  const cache = new Map() // resolvedMirrorDir → { scannedAt, files } | { failedAt }
+  const inflight = new Map() // resolvedMirrorDir → Promise
+  const RETRY_AFTER_MS = 60 * 1000
+
+  const keyOfDir = (mirrorDir) => {
+    try { return path.resolve(String(mirrorDir)) } catch { return String(mirrorDir || '') }
+  }
+
+  /**
+   * Scan (or return the cached scan of) one mirror's remote workspace.
+   * @param {{pool: {sftp: Function}, ws: string, mirrorDir: string, force?: boolean}} arg
+   * @returns {Promise<{scannedAt: number, files: Array}|null>}
+   */
+  const refresh = ({ pool, ws, mirrorDir, force = false }) => {
+    if (!pool || typeof pool.sftp !== 'function' || !ws || !mirrorDir) return Promise.resolve(null)
+    const key = keyOfDir(mirrorDir)
+    const cur = cache.get(key)
+    if (!force && cur && cur.files) return Promise.resolve(cur)
+    if (!force && cur && cur.failedAt && Date.now() - cur.failedAt < RETRY_AFTER_MS) return Promise.resolve(null)
+    if (inflight.has(key)) return inflight.get(key)
+    const job = (async () => {
+      try {
+        const sftp = await pool.sftp()
+        const files = await scanInstructionFiles(sftp, ws)
+        const synced = syncInstructionsToMirror(files, mirrorDir)
+        const entry = {
+          scannedAt: Date.now(),
+          files: files.map((f) => ({
+            rel: f.rel,
+            remote: f.remote,
+            size: f.size,
+            headings: f.headings,
+            mirrored: synced.present.has(f.rel),
+          })),
+        }
+        cache.set(key, entry)
+        return entry
+      } catch {
+        // Negative-cache: the machine may simply be offline; retry at most
+        // once a minute, not once per prompt assembly.
+        cache.set(key, { failedAt: Date.now() })
+        return null
+      } finally {
+        inflight.delete(key)
+      }
+    })()
+    inflight.set(key, job)
+    return job
+  }
+
+  /** The cached index for a mirror, or null when unknown/failed. */
+  const get = (mirrorDir) => {
+    const e = cache.get(keyOfDir(mirrorDir))
+    return e && e.files ? e : null
+  }
+
+  /** Fire-and-forget refresh for prompt-assembly time: starts a scan only
+   *  when nothing is known about the mirror yet (recent failures included). */
+  const note = ({ pool, ws, mirrorDir }) => {
+    if (cache.has(keyOfDir(mirrorDir))) return
+    refresh({ pool, ws, mirrorDir }).catch(() => { /* guarded inside */ })
+  }
+
+  return { refresh, get, note, _cache: cache }
+}

package/lib/openssh.js

@@ -785,7 +785,16 @@ export class SystemOpenSshPool {
         throw new Error('ssh target changed while opening sftp')
       }
       this._sftpChild = child
-      return buildSftpSurface(sftp, { commandTimeoutMs: this.config.commandTimeoutMs })
+      return buildSftpSurface(sftp, {
+        commandTimeoutMs: this.config.commandTimeoutMs,
+        onTimeout: () => {
+          // A timed-out SFTP session is dead: kill the child and drop the cached
+          // session so the next call re-handshakes instead of queueing behind the
+          // wedged one (issue #65).
+          try { child.kill() } catch { /* already gone */ }
+          drop()
+        },
+      })
     })
     // Never cache a rejected open: the next call must retry rather than get the
     // same error back forever (a failed handshake is usually transient).

package/lib/pool.js

@@ -197,6 +197,8 @@ export class SshPool {
     this.onReady = null
     /** Optional hook called when the pool closes. */
     this.onCloseHook = null
+    /** Consecutive SFTP subchannel-open timeouts (issue #65). */
+    this._sftpTimeouts = 0
   }
 
   resolveKeyPath() {
@@ -324,6 +326,7 @@ export class SshPool {
           return
         }
         this.client = client
+        this._sftpTimeouts = 0
         resolve(client)
         if (this.onReady) { try { this.onReady(client) } catch {} }
       })
@@ -684,10 +687,25 @@ export class SshPool {
                   }
                   return reject(new Error('ssh sftp failed: ' + ((err && err.message) || err)))
                 }
+                // A successful open proves the connection healthy: the strike
+                // counter counts CONSECUTIVE timeouts, so it resets here —
+                // two unrelated transient blips hours apart must not tear down
+                // a fine connection.
+                this._sftpTimeouts = 0
                 // The promisified surface (timeouts, dead-channel fail-fast,
                 // range reads) is shared verbatim with the system-OpenSSH
                 // backend — see lib/sftp-surface.js for the rules it encodes.
-                resolve(buildSftpSurface(sftp, { commandTimeoutMs: this.config.commandTimeoutMs }))
+                resolve(buildSftpSurface(sftp, {
+                  commandTimeoutMs: this.config.commandTimeoutMs,
+                  onTimeout: () => {
+                    // A timed-out SFTP subchannel is dead: close it so the next
+                    // operation does not queue behind the wedged one, and count
+                    // the strike so a second consecutive timeout tears down the
+                    // whole pooled connection (issue #65).
+                    try { sftp.end() } catch { /* already gone */ }
+                    this._noteSftpTimeout()
+                  },
+                }))
               })
             } catch (e) {
               clearAttempt()
@@ -699,6 +717,16 @@ export class SshPool {
     )
   }
 
+  /**
+   * Count a timed-out SFTP subchannel open. A second consecutive timeout means
+   * the pooled connection itself is wedged (issue #65): tear it down so the
+   * next sftp() call re-handshakes instead of queueing behind the dead one.
+   */
+  _noteSftpTimeout() {
+    this._sftpTimeouts = (this._sftpTimeouts || 0) + 1
+    if (this._sftpTimeouts >= 2) this.invalidate()
+  }
+
   /**
    * Drop the cached client and force a fresh connection on the next call.
    * Called when a channel open fails (e.g. "Channel open failure: open

package/lib/remote-fs.js

@@ -98,6 +98,17 @@ export async function removeRemoteTree(sftp, p, maxFiles = 2000) {
   return removed
 }
 
+/** MIME types for image formats the preview panel can render inline. */
+const IMAGE_MIME_TYPES = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  bmp: 'image/bmp',
+}
+
 function looksBinary(buf) {
   const n = Math.min(buf.length, 8192)
   for (let i = 0; i < n; i++) if (buf[i] === 0) return true
@@ -107,6 +118,14 @@ function looksBinary(buf) {
 /**
  * Read a remote file for the sidebar/editor. Oversized files use a range read
  * (`readPartial`) so we never `fastGet` the whole blob onto disk.
+ *
+ * Images are the exception (issue #66): a PREFIX of an image is a broken
+ * picture, not a preview, so for a recognised image extension the caller's
+ * text-oriented cap is skipped and the file is read whole up to the hard 2MB
+ * ceiling; the panel renders it inline as `<img src="data:…">`. An image past
+ * the ceiling degrades to the plain binary stub + download button rather than
+ * shipping a guaranteed-broken half render. (`<img>` is also the safe sink
+ * for SVG: unlike inline markup it cannot run the file's scripts.)
  */
 export async function previewRemoteFile(sftp, target, opts = {}) {
   const {
@@ -114,7 +133,10 @@ export async function previewRemoteFile(sftp, target, opts = {}) {
     encoding = 'utf-8',
     decodeBuf = (buf) => buf.toString('utf8'),
   } = opts
-  const cap = Math.min(Math.max(Number(maxBytes) || 256 * 1024, 1024), 2 * 1024 * 1024)
+  const hardCap = 2 * 1024 * 1024
+  const name = String(target).split(/[\\/]/).pop() || ''
+  const imageMime = IMAGE_MIME_TYPES[(name.split('.').pop() || '').toLowerCase()]
+  const cap = imageMime ? hardCap : Math.min(Math.max(Number(maxBytes) || 256 * 1024, 1024), hardCap)
   const st = await sftp.stat(target)
   const mtime = st && typeof st.mtime === 'number' ? st.mtime : 0
   const size = st && typeof st.size === 'number' ? st.size : 0
@@ -131,6 +153,9 @@ export async function previewRemoteFile(sftp, target, opts = {}) {
   } else {
     buf = await sftp.readFile(target)
   }
+  if (imageMime && !truncated) {
+    return { ok: true, binary: false, image: true, mime: imageMime, content: buf.toString('base64'), truncated, size, mtime }
+  }
   if (looksBinary(buf)) {
     return {
       ok: true, binary: true, size, mtime,

package/lib/sftp-surface.js

@@ -26,7 +26,7 @@ import { toSftpPath } from './paths.js'
  * @param {number} opts.commandTimeoutMs - per-operation timeout.
  * @returns {object} promisified sftp surface.
  */
-export function buildSftpSurface(sftp, { commandTimeoutMs }) {
+export function buildSftpSurface(sftp, { commandTimeoutMs, onTimeout }) {
   // A dead channel must fail fast (see the header). ssh2's SFTP instance and the
   // system-OpenSSH engine both emit these, so one hook covers both backends.
   let dead = false
@@ -39,12 +39,19 @@ export function buildSftpSurface(sftp, { commandTimeoutMs }) {
   const withTimeout = (fn) => (...args) =>
     new Promise((resolve, reject) => {
       if (dead) return reject(new Error('sftp channel closed'))
-      const timer = setTimeout(() => reject(new Error('sftp operation timed out')), commandTimeoutMs)
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        markDead()
+        if (typeof onTimeout === 'function') { try { onTimeout() } catch { /* best effort */ } }
+        reject(new Error('sftp operation timed out'))
+      }, commandTimeoutMs)
       const finish = (err, value) => {
         clearTimeout(timer)
+        if (timedOut) return
         err ? reject(err) : resolve(value)
       }
-      try { fn(...args, finish) } catch (err) { clearTimeout(timer); reject(err) }
+      try { fn(...args, finish) } catch (err) { clearTimeout(timer); if (!timedOut) reject(err) }
     })
   const P = (p) => toSftpPath(p)
   return {
@@ -55,7 +62,43 @@ export function buildSftpSurface(sftp, { commandTimeoutMs }) {
     rmdir: (dir) => withTimeout((d, cb) => sftp.rmdir(d, cb))(P(dir)),
     unlink: (p) => withTimeout((d, cb) => sftp.unlink(d, cb))(P(p)),
     rename: (p, d) => withTimeout((a, b, cb) => sftp.rename(a, b, cb))(P(p), P(d)),
+    // POSIX rename(2) semantics: atomically REPLACE an existing destination.
+    // Plain SSH_FXP_RENAME fails when the target exists (OpenSSH's sftp-server
+    // enforces that even though it advertises posix-rename@openssh.com — ssh2
+    // only sends the extension when asked explicitly, verified against
+    // OpenSSH_9.6 in issue #65). Servers with the extension get one atomic
+    // request; servers without it get the move-aside dance, whose every hop
+    // targets a path that does not exist, which plain RENAME always permits.
+    // rw_edit's atomic write depends on this — without it every edit of an
+    // existing file fails with a bare "Failure".
+    renameOverwrite: (p, d) => withTimeout((a, b, cb) => {
+      const ext = sftp._extensions && sftp._extensions['posix-rename@openssh.com']
+      if (ext === '1' && typeof sftp.ext_openssh_rename === 'function') {
+        return sftp.ext_openssh_rename(a, b, cb)
+      }
+      const bak = `${b}.dsh-remote-bak-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`
+      sftp.rename(b, bak, (e1) => {
+        if (e1) {
+          // Destination absent → a plain rename is already overwrite-safe.
+          if (/no such/i.test(String((e1 && e1.message) || e1))) return sftp.rename(a, b, cb)
+          return cb(e1)
+        }
+        sftp.rename(a, b, (e2) => {
+          if (e2) {
+            // Roll the original back into place before reporting the failure.
+            return sftp.rename(bak, b, () => cb(e2))
+          }
+          // Best effort: a leftover backup must not fail the operation.
+          sftp.unlink(bak, () => cb(null))
+        })
+      })
+    })(P(p), P(d)),
     realpath: (p) => withTimeout((d, cb) => sftp.realpath(d, cb))(P(p)),
+    // Attribute write (chmod semantics live in setstat at the protocol level,
+    // so BOTH backends — ssh2's SFTPWrapper and its raw protocol SFTP — answer
+    // this one shape). Used by rw_edit to restore the original mode after an
+    // atomic rename replace (issue #65).
+    setstat: (p, attrs) => withTimeout((d, a, cb) => sftp.setstat(d, a, cb))(P(p), attrs),
     readFile: (p) => withTimeout((d, cb) => sftp.readFile(d, cb))(P(p)),
     writeFile: (p, data) => withTimeout((d, data2, cb) => sftp.writeFile(d, data2, cb))(P(p), data),
     fastGet: (p, lp) => withTimeout((d, l, cb) => sftp.fastGet(d, l, cb))(P(p), lp),

package/lib/sshconfig.js

@@ -32,11 +32,21 @@ import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSy
 import { homedir } from 'node:os'
 import path from 'node:path'
 
-/** Default location of the user's ssh config. */
-export const sshConfigPath = () => path.join(homedir(), '.ssh', 'config')
+/** Default location of the user's ssh config. An env override exists so tests
+ *  (and any deployment that isolates its home directory) can point the plugin
+ *  at a substitute file instead of the real ~/.ssh/config. */
+export const sshConfigPath = () => {
+  const env = process.env.DSH_REMOTE_SSH_CONFIG
+  if (env && String(env).trim()) return path.resolve(String(env).trim())
+  return path.join(homedir(), '.ssh', 'config')
+}
 
 /** Directory `Include` paths are resolved against (ssh_config(5)). */
-export const sshConfigDir = () => path.join(homedir(), '.ssh')
+export const sshConfigDir = () => {
+  const env = process.env.DSH_REMOTE_SSH_CONFIG
+  if (env && String(env).trim()) return path.dirname(path.resolve(String(env).trim()))
+  return path.join(homedir(), '.ssh')
+}
 
 /** Parameters the resolver cares about, lowercase (as parsed). */
 const KNOWN_PARAMS = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote",
-  "version": "0.8.51",
+  "version": "0.8.52",
   "description": "Remote-work assistant for DeepSeek Harness: connect SSH (password/key/agent/keyboard-interactive/proxy jump), pick a remote workspace, operate on it with 22 rw_* tools (incl. rw_edit/rw_stat/rw_mkdir/rw_remove/rw_move/rw_forward), conflict-aware mirror sync, one-click remote dsh deploy + web UI attach, port forwarding, optional side-bar remote file editing, audit log, keychain passwords.",
   "license": "MIT",
   "author": "flymysql <flyphp@outlook.com>",