dsh-remote 0.8.50 → 0.8.52

package/README.en.md

@@ -276,6 +276,7 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 | `webInstallPrefix` | string | `''` | where an automatic deployment installs dsh; empty means `$HOME/.dsh-remote/dsh` (no system directory, no PATH change) |
 | `webInstallVersion` | string | `0.1.5-rc.2` | dsh version an automatic deployment installs; the default is the first that can start the web surface on Linux |
 | `webInstallRegistry` | string | `''` | npm registry for the install; **empty keeps the remote's own config**, so an internal mirror is never overridden |
+| `localTools` | string | `bootstrap` | which `rw_*` tools a LOCAL session (cwd outside every remote mirror) sees (issue #63): `bootstrap` keeps only the configuration loop `rw_machines`/`rw_connect`/`rw_pick_workspace` (the other 19 refuse a local session with "this session is LOCAL", so exposing them just wastes schema budget); `none` hides all `rw_*` (remote setup happens via the settings page only); `all` restores the legacy full surface. REMOTE sessions (cwd inside a mirror) always see everything; an invalid value degrades to `bootstrap` |
 
 > The authoritative list is the `Config` schema in `lib/index.js`; this table mirrors it.
 
@@ -284,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

@@ -258,6 +258,7 @@ scripts/dev-run.sh --status    # 是否在运行
 | `webInstallPrefix` | string | `''` | 自动部署装到远端的哪个目录；留空用 `$HOME/.dsh-remote/dsh`（不写系统目录、不改 PATH） |
 | `webInstallVersion` | string | `0.1.5-rc.2` | 自动部署安装的 dsh 版本；默认值是第一个在 Linux 上能启动 web 的版本 |
 | `webInstallRegistry` | string | `''` | 安装用的 npm 源；**留空沿用远端自己的配置**，不会覆盖内网镜像 |
+| `localTools` | string | `bootstrap` | 本地 session（cwd 不在远程镜像里）暴露哪些 `rw_*` 工具（issue #63）：`bootstrap`=只暴露配置闭环 `rw_machines`/`rw_connect`/`rw_pick_workspace`（其余 19 个在本地 session 必然报 "this session is LOCAL"，暴露只是白占 schema）；`none`=完全不暴露 `rw_*`（远程配置只能走设置页）；`all`=旧的 full 暴露。远程 session（cwd 在镜像里）不受影响，始终全量；非法值按 `bootstrap` 处理 |
 
 > 权威清单是 `lib/index.js` 里的 `Config` schema，本表与之一致。
 
@@ -273,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'
@@ -99,6 +100,35 @@ export function win32FolderPickScript() {
   )
 }
 
+/** The rw_* tools a LOCAL session keeps under `localTools: 'bootstrap'`
+ *  (issue #63): exactly the configuration loop — list machines, connect, pick
+ *  a workspace. Every other rw_* tool needs a mirror-bound session and refuses
+ *  a local one with "this session is LOCAL", so keeping it visible only spends
+ *  schema budget. Exported so the test suite pins the set against the real
+ *  registrations. */
+export const LOCAL_BOOTSTRAP_TOOLS = ['rw_machines', 'rw_connect', 'rw_pick_workspace']
+
+/** Normalize the `localTools` config value (issue #63). Anything unrecognized
+ *  degrades to the safe default 'bootstrap' rather than disabling the filter
+ *  (a typo must not silently re-expose the dead surface the user asked to
+ *  hide) — mirroring how an unknown value would otherwise be mistaken for
+ *  'all'. */
+export function normalizeLocalTools(value) {
+  const v = String(value || '').trim().toLowerCase()
+  return v === 'none' || v === 'all' ? v : 'bootstrap'
+}
+
+/** rw_pick_workspace's closing "what next" sentence (issue #63). In a LOCAL
+ *  session `rw_sync` cannot run — the mirror path must be opened as a NEW
+ *  session first, because tool routing keys on the session's cwd and picking
+ *  a workspace does not change it. Only a mirror-bound (or caller-context-
+ *  less) session can sync right away. */
+export function pickWorkspaceNextStep(localSession) {
+  return localSession
+    ? 'NOTE: this session is LOCAL — rw_sync and the other remote tools refuse to run here. Open a session whose workspace IS the local mirror path above, then run rw_sync there to download the remote files.'
+    : 'Run rw_sync to download its files into the local mirror.'
+}
+
 // Web and Desktop share the SSH tools; each optional UI transport is attached
 // reactively below, so service startup order does not drop the JSON routes.
 export const inject = ['tools', 'systemPrompt']
@@ -235,6 +265,16 @@ export const Config = z.object({
   /** npm registry to install from. Empty uses the remote's own npm config, which
    *  is what an internal mirror needs to stay in effect. */
   webInstallRegistry: z.string().default(''),
+  /** Which rw_* tools a LOCAL session (session cwd is NOT a remote-workspaces
+   *  mirror) sees (issue #63): `bootstrap` (default) exposes only the
+   *  configuration loop — rw_machines / rw_connect / rw_pick_workspace — since
+   *  the other tools can never succeed there (they refuse with "this session
+   *  is LOCAL") and exposing them only spends ~4k tokens of schema per request;
+   *  `none` hides every rw_* tool (remote setup then happens via the settings
+   *  page only); `all` keeps the legacy full surface. A REMOTE session (cwd
+   *  inside a mirror) always sees all tools, and an invalid value falls back
+   *  to `bootstrap`. (schemastery 3.18 has no .enum — validated in code.) */
+  localTools: z.string().default('bootstrap'),
 })
 
 // ── shell / path helpers (pure implementations in lib/paths.js) ───────────
@@ -1085,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.
@@ -1186,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))
   }
@@ -1575,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)' },
@@ -1595,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
@@ -1602,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)
@@ -1710,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 }))
         }
@@ -1786,8 +1956,17 @@ 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.
         return {
-          text: `Remote workspace set to ${shown} on ${b.username}@${b.host}.\nLocal mirror (native workspace path): ${local}\n\nRun rw_sync to download its files into the local mirror.`,
+          text: `Remote workspace set to ${shown} on ${b.username}@${b.host}.\nLocal mirror (native workspace path): ${local}\n\n${pickWorkspaceNextStep(b.local)}`,
         }
       },
     }),
@@ -1836,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()
       },
     }),
 
@@ -2095,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)` }
       },
@@ -2507,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
@@ -2520,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.
@@ -2535,6 +2754,39 @@ export async function apply(ctx, config) {
     },
   })
 
+  // ── local-session tool visibility (issue #63) ────────────────────────────
+  // All rw_* tools register globally (at registration time there is no session
+  // to consult), but in a LOCAL session the operation tools can never succeed:
+  // bindingFor() refuses them with "this session is LOCAL". Exposing them
+  // anyway costs every local request a few thousand tokens of dead schema.
+  // The `system-prompt/assemble` waterfall is where the final per-request tool
+  // list passes with the calling agent attached, so the SAME cwd test the
+  // prompt section above already performs can trim the list there. A session
+  // whose cwd maps to a mirror keeps the full surface; anything else — a
+  // plain local directory, or a mirror whose meta is missing/unparsable
+  // (resolveMirror reports no binding; bindingFor refuses it as local too) —
+  // is reduced per config.localTools. An assembly without agent/cwd is left
+  // alone, matching bindingFor's "no caller context" semantics. `ctx.on` is
+  // cordis-core, but guard like the other
+  // optional surfaces: a minimal embedding (or a small test double) without
+  // event support simply keeps the legacy full surface.
+  if (typeof ctx.on === 'function') {
+    ctx.on('system-prompt/assemble', async (_assembly, assembleContext, next) => {
+      const assembled = await next()
+      const mode = normalizeLocalTools(config.localTools)
+      if (mode === 'all') return assembled
+      const agent = assembleContext && assembleContext.agent
+      const cwd = agent && agent.session && agent.session.header && agent.session.header.cwd
+      if (!cwd) return assembled // no caller context → not definitively local
+      const { remotePath, machine } = resolveMirrorForLocal(String(cwd))
+      if (remotePath && machine) return assembled // remote session → full surface
+      const tools = (assembled.tools || []).filter(
+        (t) => !t.name || !t.name.startsWith('rw_') || (mode === 'bootstrap' && LOCAL_BOOTSTRAP_TOOLS.includes(t.name)),
+      )
+      return { ...assembled, tools }
+    })
+  }
+
   // ── slash commands ─────────────────────────────────────────────────────────
   const commands = ctx.get('commands')
   if (commands !== undefined) {
@@ -3118,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
@@ -3159,6 +3419,7 @@ export async function apply(ctx, config) {
                 machine: sanitizeMachine(rec),
                 machines: machinesForClient(),
                 currentId: store.currentId,
+                ...(reboundMirrors ? { reboundMirrors } : {}),
                 ...(warning ? { warning, warningDetail } : {}),
                 ...(sshConfigWarning ? { sshConfigWarning } : {}),
               })