dsh-remote 0.8.10 → 0.8.12

package/lib/index.js

@@ -39,6 +39,7 @@ import { importableEntries, sshConfigPath, readSshConfigText } from './sshconfig
 import { saveSecret, getSecret, deleteSecret, platformBackend } from './credential.js'
 import { syncTree, pushTree, loadSyncState, saveSyncState, pushOneFile } from './sync.js'
 import { searchTree } from './search.js'
+import { resolveMirror, poolKey } from './binding.js'
 import { TaskManager } from './tasks.js'
 import { ForwardManager } from './forwards.js'
 import { selfDir, readVersion, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode } from './update.js'
@@ -859,6 +860,106 @@ export async function apply(ctx, config) {
     })
   }
 
+  // ── per-machine SSH pools (session-bound) ─────────────────────────────────
+  // The `pool` above stays the ACTIVE-machine pool: it backs the settings page,
+  // the workspace picker routes, and `rw_connect`, whose semantics are "switch
+  // the active machine". Session-bound tool calls must not go through it —
+  // `setTarget()` rewrites the shared `config` identity and closes the live
+  // connection, so two sessions on different machines would take the pool from
+  // each other and commands would land on the wrong host (issue #25).
+  //
+  // Instead each machine gets its own pool, keyed by its stable identity. A
+  // session resolves its machine from its own workspace mirror, so concurrent
+  // sessions on different hosts never share a connection. Sessions on the SAME
+  // machine still share one, preserving the single-connection + keepalive model.
+
+  /** Deployment-varying tunables shared by every pool, owned by the live plugin
+   *  Config so a settings change reaches existing pools. Identity, credential,
+   *  and per-machine policy fields (`hostKeyMode`, `shell`, `proxy`) are
+   *  deliberately excluded — those are pinned per pool from the machine record,
+   *  and re-copying them from the shared config is exactly the bug this
+   *  registry fixes. */
+  const TUNABLE_KEYS = [
+    'connectTimeoutMs', 'commandTimeoutMs', 'maxOutputChars', 'maxFileBytes', 'encoding',
+  ]
+  const syncTunables = (target) => {
+    for (const k of TUNABLE_KEYS) {
+      if (Object.prototype.hasOwnProperty.call(config, k)) target[k] = config[k]
+    }
+    return target
+  }
+
+  const machinePools = new Map()
+  ctx.effect(() => () => {
+    for (const p of machinePools.values()) {
+      try { p.close() } catch { /* a pool already torn down by its own error path */ }
+    }
+    machinePools.clear()
+  }, 'dsh-remote.machine-pools')
+
+  /** Registry record for a resolved mirror origin, so a session-bound pool gets
+   *  the machine's real credentials (key path, passphrase, agent, proxy) rather
+   *  than only the host/user/port the mirror meta records.
+   *
+   *  An EPHEMERAL connection (rw_connect save:false) is not in the registry but
+   *  is still a legitimate credential source for a pool the same process later
+   *  resolves for that identity: without it a mirror picked on a temporary
+   *  connection would resolve to an empty-credential pool and fail to connect. */
+  const machineRecordFor = ({ host, port, username }) =>
+    (ephemeral && ephemeral.host === host && Number(ephemeral.port) === Number(port) && (ephemeral.username || '') === (username || '')
+      ? ephemeral
+      : null)
+    || machines.find((m) => m.host === host && Number(m.port) === Number(port) && (m.username || '') === (username || ''))
+    || null
+
+  /**
+   * Get (or lazily create) the dedicated pool for one remote identity.
+   * @param {{host: string, port: number, username: string}} target - the mirror-recorded origin.
+   * @returns {SshPool} the pool pinned to that identity; never the active-machine pool.
+   */
+  const poolForMachine = (target) => {
+    const key = poolKey(target)
+    const rec = machineRecordFor(target)
+    const existing = machinePools.get(key)
+    if (existing) {
+      syncTunables(existing.config)
+      // Re-read credentials and per-machine policy from the registry: editing a
+      // machine in the settings page must reach a pool created earlier, and a
+      // pool holding a stale password would keep failing to reconnect.
+      if (rec) {
+        existing.config.password = rec.password || ''
+        existing.config.privateKeyPath = rec.privateKeyPath || ''
+        existing.config.passphrase = rec.passphrase || ''
+        existing.config.useAgent = !!rec.useAgent
+        existing.config.keyboardInteractive = !!rec.keyboardInteractive
+        existing.config.proxy = rec.proxy || undefined
+        existing.config.hostKeyMode = rec.hostKeyMode || config.hostKeyMode
+      }
+      return existing
+    }
+    const poolConfig = syncTunables({
+      ...config,
+      host: target.host,
+      port: Number(target.port) || 22,
+      username: target.username || (rec && rec.username) || 'root',
+      password: (rec && rec.password) || '',
+      privateKeyPath: (rec && rec.privateKeyPath) || '',
+      passphrase: (rec && rec.passphrase) || '',
+      useAgent: rec ? !!rec.useAgent : !!config.useAgent,
+      keyboardInteractive: rec ? !!rec.keyboardInteractive : !!config.keyboardInteractive,
+      proxy: (rec && rec.proxy) || undefined,
+      hostKeyMode: (rec && rec.hostKeyMode) || config.hostKeyMode,
+      // Identity-pinned pools never carry the shared active workspace: a
+      // session passes its own mirror-resolved remote path explicitly.
+      workspace: '',
+    })
+    const created = new SshPool(poolConfig)
+    // Keychain-backed passwords resolve against THIS pool's machine record.
+    created.passwordResolver = async () => machinePassword(rec || { id: '', password: poolConfig.password })
+    machinePools.set(key, created)
+    return created
+  }
+
   const setCurrent = async (id) => {
     if (!id) {
       // Explicit "active remote = none": saved machines stay in the registry
@@ -955,10 +1056,24 @@ export async function apply(ctx, config) {
   }
 
   // ── audit log ─────────────────────────────────────────────────────────────
-  const audit = (op, cmd, code) => {
+  /**
+   * Append one audit line. `target` names the machine the operation really ran
+   * on and must be passed by every session-bound caller: the shared `config`
+   * identity belongs to the ACTIVE machine, which can be a different host than
+   * the session that issued the command, so defaulting to it would
+   * misattribute the operation.
+   * @param {string} op - operation name.
+   * @param {string} cmd - command text or path detail.
+   * @param {number|null} code - exit code, or null when not applicable.
+   * @param {{host?: string, username?: string, port?: number}} [target] - machine acted on; defaults to the active machine.
+   */
+  const audit = (op, cmd, code, target) => {
     if (!config.auditLog) return
+    const host = (target && target.host) || config.host
+    const user = (target && target.username) || config.username
+    const port = (target && target.port) || config.port
     try {
-      const line = [new Date().toISOString(), `${config.username || '?'}@${config.host || '?'}:${config.port}`, op, code == null ? '-' : String(code), String(cmd || '').replace(/\s+/g, ' ').slice(0, 400)].join(' | ') + '\n'
+      const line = [new Date().toISOString(), `${user || '?'}@${host || '?'}:${port}`, op, code == null ? '-' : String(code), String(cmd || '').replace(/\s+/g, ' ').slice(0, 400)].join(' | ') + '\n'
       appendFileSync(auditFile(), line, 'utf8')
     } catch {}
   }
@@ -998,22 +1113,27 @@ export async function apply(ctx, config) {
     if (!entry || !entry.pending.size) return
     const rels = [...entry.pending]
     entry.pending.clear()
-    const ws = wsPath()
-    if (!ws || mirrorDirFor(ws, config.host, config.username, config.port) !== localDir) return
+    // Resolve the destination from the WATCHED MIRROR, not from the active
+    // machine: a watcher outlives any one session, so gating on the active
+    // machine made it silently stop pushing (and, before per-machine pools,
+    // risked pushing one host's mirror through another host's connection).
+    const { remotePath: ws, machine } = resolveMirrorForLocal(localDir)
+    if (!ws || !machine) return
+    const target = poolForMachine(machine)
     let sftp
-    try { sftp = await pool.sftp() } catch { return }
+    try { sftp = await target.sftp() } catch { return }
     const matcher = ignoreMatcher()
     const state = loadSyncState(localDir)
     const next = { ...state }
     if (rels.includes('*')) {
       const r = await pushTree(sftp, localDir, ws, { maxFiles: 500, maxFileBytes: config.maxFileBytes, isIgnored: matcher, state: next })
       Object.assign(next, r.nextState)
-      for (const c of r.stats.conflicts) audit('auto-push-conflict', `push ${c.path}`, 1)
+      for (const c of r.stats.conflicts) audit('auto-push-conflict', `push ${c.path}`, 1, machine)
     } else {
       for (const rel of rels) {
         const r = await pushOneFile(sftp, localDir, ws, rel, { maxFileBytes: config.maxFileBytes, isIgnored: matcher, state: next })
         if (r.status === 'pushed' && r.state) Object.assign(next, r.state)
-        else if (r.status === 'conflict') audit('auto-push-conflict', `push ${rel}`, 1)
+        else if (r.status === 'conflict') audit('auto-push-conflict', `push ${rel}`, 1, machine)
       }
     }
     saveSyncState(localDir, next)
@@ -1047,8 +1167,11 @@ export async function apply(ctx, config) {
     autoPushWatchers.clear()
   }, 'dsh-remote.autopush')
 
-  const run = async (cmd, opts = {}) => {
-    const res = await pool.exec(cmd, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {})
+  // 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.
+  const run = async (cmd, opts = {}, p = pool) => {
+    const res = await p.exec(cmd, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {})
     const parts = []
     if (res.stdout) parts.push(res.stdout.replace(/\s+$/, ''))
     if (res.stderr) parts.push('-- stderr --\n' + res.stderr.replace(/\s+$/, ''))
@@ -1061,11 +1184,11 @@ export async function apply(ctx, config) {
 
   /** Structured listing: name + type + size + mtime + mode (SFTP protocol-level,
    * works on any remote: POSIX / cmd.exe / PowerShell). */
-  const listDirStructured = async (p) => {
+  const listDirStructured = async (p, sshPool = pool) => {
     const target = normalizeRemotePath(p || '/')
     let sftp
     try {
-      sftp = await pool.sftp()
+      sftp = await sshPool.sftp()
     } catch (err) {
       throw new Error('browse failed: ' + ((err && err.message) || err))
     }
@@ -1141,10 +1264,10 @@ export async function apply(ctx, config) {
     return [...new Set(letters)].sort().map((l) => ({ name: l + ':\\', path: l + ':\\', type: 'dir', drive: true, size: 0, mtime: 0 }))
   }
 
-  const isRemoteDir = async (p) => {
+  const isRemoteDir = async (p, sshPool = pool) => {
     const target = normalizeRemotePath(p)
     try {
-      const sftp = await pool.sftp()
+      const sftp = await sshPool.sftp()
       const st = await sftp.stat(target)
       return !!(st && st.isDirectory && st.isDirectory())
     } catch {
@@ -1180,44 +1303,26 @@ export async function apply(ctx, config) {
   const wsPath = () => (config.workspace || '').trim()
   /** Map a LOCAL path to the remote path its mirror represents ('' when the
    *  path is not inside any dsh-remote mirror). Shared by the resolve-mirror
-   *  route, the session-aware system-prompt injection, and status(). */
-  const resolveMirrorForLocal = (local) => {
-    const root = remoteWorkspacesRoot()
-    const norm = (p) => path.resolve(String(p || '')).replace(/[\\/]+$/, '') || ''
-    let matched = ''
-    let matchedRemote = ''
-    if (local && existsSync(root)) {
-      const base = norm(local)
-      for (const hostDir of readdirSync(root)) {
-        const hostPath = path.join(root, hostDir)
-        if (!statSync(hostPath, { throwIfNoEntry: false })?.isDirectory?.()) continue
-        for (const mirrorDir of readdirSync(hostPath)) {
-          const metaPath = path.join(hostPath, mirrorDir, '.dsh-remote-meta.json')
-          if (!existsSync(metaPath)) continue
-          try {
-            const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
-            const mirrorAbs = norm(path.join(hostPath, mirrorDir))
-            if (mirrorAbs === base || base.startsWith(mirrorAbs + path.sep) || base.startsWith(mirrorAbs + '/')) {
-              if (mirrorAbs.length > matched.length) {
-                matched = mirrorAbs
-                matchedRemote = String(meta.remotePath || '')
-              }
-            }
-          } catch { /* skip unparsable meta */ }
-        }
-      }
-    }
-    return { mirrorDir: matched || null, remotePath: matchedRemote || '' }
-  }
+   *  route, the session-aware system-prompt injection, and status().
+   *
+   *  `machine` carries the mirror's recorded origin (`host`/`port`/`username`
+   *  from `.dsh-remote-meta.json`), or null when the path is not inside a
+   *  mirror. That origin is what makes a session's remote target authoritative
+   *  without consulting the mutable active-machine state, so a concurrent
+   *  session switching machines cannot redirect this session's commands. */
+  const resolveMirrorForLocal = (local) => resolveMirror(local, remoteWorkspacesRoot())
   if (config.autoPush && wsPath()) {
     startAutoPush(mirrorDirFor(wsPath(), config.host, config.username, config.port))
   }
-  /** The remote path the CURRENT agent session is really bound to, or '' when
-   *  the session is a plain local one. Walks the mirror registry (host side
-   *  copy of the resolve-mirror logic) so status / prompt / sidebar agree.
-   *  `sessionId` narrows to one session; without it the first live session's
-   *  cwd is used (best effort — status is informational, the per-session
-   *  resolve-mirror endpoint is authoritative). */
+  /** The remote path one agent session is bound to, or '' when that session is
+   *  a plain local one. Walks the mirror registry (host side copy of the
+   *  resolve-mirror logic) so status / prompt / sidebar agree.
+   *
+   *  `sessionId` narrows to one session. WITHOUT it the first live session's cwd
+   *  is used, which is only meaningful for the machine-scoped settings view:
+   *  with several live sessions the "first" one is arbitrary and may belong to
+   *  another machine. Tool calls must never route through this — they resolve
+   *  their own session through `bindingFor()`, which is authoritative. */
   const sessionRemotePath = (sessionId) => {
     let cwd = ''
     try {
@@ -1233,6 +1338,111 @@ export async function apply(ctx, config) {
     if (!cwd) return ''
     return resolveMirrorForLocal(cwd).remotePath
   }
+
+  // ── session-bound remote binding (the authoritative tool path) ─────────────
+
+  /**
+   * Resolve the remote binding a tool call must act on, from the calling
+   * session's own workspace cwd.
+   *
+   * This is what keeps concurrent sessions independent: the machine and the
+   * workspace root both come from the session's mirror `.dsh-remote-meta.json`,
+   * never from the mutable active-machine state, so another session switching
+   * machines cannot redirect this call. Sessions on the same machine resolve to
+   * the same key and share one pool.
+   *
+   * @param {object} [exec] - the tool's `ToolRunContext`; `exec.agent.session.header.cwd` identifies the caller.
+   * @returns {{pool: SshPool, ws: string, host: string, username: string, port: number, mirrorDir: string|null, bound: boolean, local: boolean}}
+   *   `bound` is true only for a session whose cwd resolves to a mirror. A
+   *   caller with a cwd that is NOT a mirror is a local session: `local` is
+   *   true and the active-machine values are returned for machine-scoped
+   *   reporting (`rw_info`) — session-scoped tools must refuse it instead,
+   *   which is what {@link requireBinding} enforces.
+   */
+  const bindingFor = (exec) => {
+    const cwd = exec?.agent?.session?.header?.cwd
+    if (cwd) {
+      const { remotePath, machine, mirrorDir } = resolveMirrorForLocal(String(cwd))
+      if (remotePath && machine) {
+        return {
+          pool: poolForMachine(machine),
+          ws: remotePath,
+          host: machine.host,
+          username: machine.username,
+          port: machine.port,
+          mirrorDir,
+          bound: true,
+          local: false,
+        }
+      }
+    }
+    return {
+      pool,
+      ws: wsPath(),
+      host: config.host,
+      username: config.username,
+      port: config.port,
+      mirrorDir: wsPath() ? mirrorDirFor(wsPath(), config.host, config.username, config.port) : null,
+      bound: false,
+      // A caller that identified itself with a cwd, yet resolved to no mirror,
+      // is definitively a LOCAL session. Distinguish it from "no caller
+      // context at all", where the active machine is still the right answer.
+      local: !!cwd,
+    }
+  }
+
+  /**
+   * Binding for a tool that requires a remote workspace, with a diagnostic
+   * refusal when none is resolvable. Failing loud here is the point: silently
+   * falling back to the active machine is how a command reached the wrong host.
+   * @param {object} exec - the tool's `ToolRunContext`.
+   * @param {string} tool - tool name, used in the error message.
+   * @returns {ReturnType<typeof bindingFor>} a binding with `bound: true`.
+   */
+  const requireBinding = (exec, tool) => {
+    const b = bindingFor(exec)
+    // A LOCAL session must be refused even when an active machine happens to
+    // have a workspace: inheriting it is precisely how a command reaches a host
+    // the caller never asked for. Checking only `!b.ws` missed this, because
+    // the active machine's workspace is usually non-empty.
+    if (b.local) {
+      throw new Error(
+        `${tool}: this session is LOCAL — its workspace is not a remote mirror, `
+        + 'so there is no remote host to act on. Refusing rather than falling back to the active machine '
+        + `(${config.username || '?'}@${config.host || '?'}), which belongs to a different session. `
+        + 'Use rw_connect + rw_pick_workspace to bind a remote workspace, then open a session in its local mirror.',
+      )
+    }
+    if (!b.ws) {
+      throw new Error(
+        `${tool}: no remote workspace set — call rw_connect then rw_pick_workspace first.`,
+      )
+    }
+    if (!b.host) throw new Error(`${tool}: no remote host resolved for this session — run rw_connect first.`)
+    return b
+  }
+
+  /**
+   * Binding for a tool that takes an explicit absolute remote path: it needs a
+   * resolvable MACHINE but not a workspace root. A local session is refused for
+   * the same reason as {@link requireBinding} — the active machine belongs to
+   * whoever set it, not to this caller.
+   * @param {object} exec - the tool's `ToolRunContext`.
+   * @param {string} tool - tool name, used in the error message.
+   * @returns {ReturnType<typeof bindingFor>} a binding whose `host` is non-empty.
+   */
+  const requireMachine = (exec, tool) => {
+    const b = bindingFor(exec)
+    if (b.local) {
+      throw new Error(
+        `${tool}: this session is LOCAL — its workspace is not a remote mirror, `
+        + 'so there is no remote host to act on. Refusing rather than falling back to the active machine '
+        + `(${config.username || '?'}@${config.host || '?'}), which belongs to a different session.`,
+      )
+    }
+    if (!b.host) throw new Error(`${tool}: no remote host for this session — run rw_connect first`)
+    return b
+  }
   const status = () => ({
     host: config.host,
     port: config.port,
@@ -1276,27 +1486,44 @@ export async function apply(ctx, config) {
         'Show the remote environment: host/user/port, connection health, current remote workspace path, active port forwards. Call this first to orient, or when an rw_* call fails to check connectivity. Note: remote context is session-scoped — a saved machine only becomes active when you explicitly rw_connect to it (issue #13).',
       parameters: {},
       output: textOut,
-      async execute() {
+      async execute(_args, exec) {
+        // Report THIS session's binding, not the globally active machine: the
+        // two differ whenever another session is working on another host, and
+        // reporting the active machine is what made this tool contradict itself.
+        const b = bindingFor(exec)
+        // rw_info is the orientation tool, so resolve the real platform rather
+        // than reporting "detecting…" for a pool this session has not used yet.
+        if (b.host) {
+          try { await b.pool.detect() } catch { /* unreachable host → the ping below reports it */ }
+        }
         const s = status()
-        const lines = [
-          `Remote host: ${s.username || '<user>'}@${s.host || '<host>'}:${s.port}${s.activeSource !== 'machine' ? ` (source: ${s.activeSource})` : ''}`,
-          `Current remote workspace: ${s.workspace || '(none — call rw_connect then rw_pick_workspace to set one)'}`,
-          `Local mirror: ${s.localMirror || '(none)'}`,
-          `Session remote context: ${s.sessionRemotePath ? s.sessionRemotePath : '(this session is LOCAL — no remote workspace bound)'}`,
-          `Connected: ${s.connected ? 'yes' : 'no'}`,
-          `Remote shell: ${s.platform === 'windows' ? (s.gitBash ? 'Git Bash (' + s.gitBash + ')' : 'Windows (Git Bash not found — set config.shell to a bash.exe path)') : (s.platform === 'posix' ? 'native POSIX' : 'detecting…')}`,
-          `Active forwards: ${s.forwards.filter((f) => f.active).length} / ${s.forwards.length}`,
-          `Host key: ${s.hostKeyKnown ? 'trusted' : 'not yet trusted'} (mode=${s.hostKeyMode})`,
-          '',
-        ]
-        if (s.host && s.workspace) {
+        const lines = b.bound
+          ? [
+              `Remote host: ${b.username || '<user>'}@${b.host}:${b.port} (bound to this session's workspace)`,
+              `Current remote workspace: ${toDisplayPath(b.ws, b.pool.platform)}`,
+              `Local mirror: ${b.mirrorDir || '(none)'}`,
+              `Connected: ${b.pool.client ? 'yes' : 'no'}`,
+              `Remote shell: ${b.pool.platform === 'windows' ? (b.pool.gitBashPath ? 'Git Bash (' + b.pool.gitBashPath + ')' : 'Windows (Git Bash not found — set config.shell to a bash.exe path)') : (b.pool.platform === 'posix' ? 'native POSIX' : 'detecting…')}`,
+              `Active forwards: ${s.forwards.filter((f) => f.active).length} / ${s.forwards.length} (forwards are machine-scoped)`,
+              `Host key: ${isHostKeyKnown(b.host, b.port) ? 'trusted' : 'not yet trusted'} (mode=${s.hostKeyMode})`,
+              '',
+            ]
+          : [
+              `Remote host: ${s.username || '<user>'}@${s.host || '<host>'}:${s.port}${s.activeSource !== 'machine' ? ` (source: ${s.activeSource})` : ''}`,
+              'Session remote context: (this session is LOCAL — no remote workspace bound)',
+              `Active machine workspace: ${s.workspace || '(none — call rw_connect then rw_pick_workspace to set one)'}`,
+              `Connected: ${s.connected ? 'yes' : 'no'}`,
+              `Host key: ${s.hostKeyKnown ? 'trusted' : 'not yet trusted'} (mode=${s.hostKeyMode})`,
+              '',
+            ]
+        if (b.host && b.ws) {
           try {
-            const res = await pool.exec('echo ok', { timeoutMs: Math.min(config.commandTimeoutMs, 8000) })
+            const res = await b.pool.exec('echo ok', { timeoutMs: Math.min(config.commandTimeoutMs, 8000) })
             if (res.signal === 'TIMEOUT') lines.push('Ping: timeout')
             else if (res.code === 0) lines.push('Ping: OK — ' + res.stdout.replace(/\s+/g, ' ').trim())
             else lines.push('Ping: FAILED — ' + (res.stderr || res.stdout || `exit ${res.code}`).trim())
           } catch (err) {
-            lines.push('Ping: FAILED — ' + friendlyMessage(err, s))
+            lines.push('Ping: FAILED — ' + friendlyMessage(err, { host: b.host, port: b.port }))
           }
         } else {
           lines.push('No host + workspace configured — call rw_connect with a host to get started.')
@@ -1376,17 +1603,28 @@ export async function apply(ctx, config) {
         path: { type: 'string', required: true, description: 'Absolute remote directory path, e.g. /home/dev/code/project or C:\\Users\\dev\\project' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_pick_workspace: path must be an absolute directory')
-        const ok = await isRemoteDir(p)
-        const shown = toDisplayPath(p, pool.platform)
+        // Picking a workspace targets the machine this session is already bound
+        // to when it has one. A LOCAL session deliberately falls back to the
+        // active machine here: this is the setup flow that runs right after
+        // rw_connect, before any mirror exists to bind to. It creates a mirror
+        // rather than reading or writing remote data, so the refusal that
+        // guards the other tools would make binding a first workspace
+        // impossible.
+        const b = bindingFor(exec)
+        if (!b.host) throw new Error('rw_pick_workspace: no remote host — call rw_connect first')
+        const ok = await isRemoteDir(p, b.pool)
+        const shown = toDisplayPath(p, b.pool.platform)
         if (!ok) return { text: `not a directory (or missing) on ${shown}` }
-        persistWorkspace(p)
-        const local = ensureMirror(p, config.host, config.username, config.port)
+        // A bound session's workspace lives in its own mirror meta, so the
+        // shared active-machine workspace is only updated for the unbound flow.
+        if (!b.bound) persistWorkspace(p)
+        const local = ensureMirror(p, b.host, b.username, b.port)
         startAutoPush(local)
         return {
-          text: `Remote workspace set to ${shown} on ${config.username}@${config.host} (saved for this machine).\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\nRun rw_sync to download its files into the local mirror.`,
         }
       },
     }),
@@ -1403,10 +1641,10 @@ export async function apply(ctx, config) {
         async: { type: 'boolean', description: 'Run in the background and return a task id (default false)' },
       },
       output: textOut,
-      async execute(args) {
-        const p = wsPath()
-        if (!p) throw new Error('rw_sync: no remote workspace set — call rw_pick_workspace first')
-        const local = mirrorDirFor(p, config.host, config.username, config.port)
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_sync')
+        const p = b.ws
+        const local = b.mirrorDir || mirrorDirFor(p, b.host, b.username, b.port)
         mkdirSync(local, { recursive: true })
         const depth = Math.min(Math.max(Number(args.depth) || 5, 1), 8)
         const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
@@ -1415,7 +1653,7 @@ export async function apply(ctx, config) {
         const runSync = async () => {
           let sftp
           try {
-            sftp = await pool.sftp()
+            sftp = await b.pool.sftp()
           } catch (err) {
             throw new Error('sftp unavailable: ' + ((err && err.message) || err))
           }
@@ -1453,10 +1691,10 @@ export async function apply(ctx, config) {
         async: { type: 'boolean', description: 'Run in the background and return a task id (default false)' },
       },
       output: textOut,
-      async execute(args) {
-        const p = wsPath()
-        if (!p) throw new Error('rw_push: no remote workspace set — call rw_pick_workspace first')
-        const local = mirrorDirFor(p, config.host, config.username, config.port)
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_push')
+        const p = b.ws
+        const local = b.mirrorDir || mirrorDirFor(p, b.host, b.username, b.port)
         if (!existsSync(local)) throw new Error(`rw_push: local mirror does not exist — run rw_sync first (${local})`)
         const maxFiles = Math.min(Math.max(Number(args.maxFiles) || 500, 1), 2000)
         const isIgnored = ignoreMatcher()
@@ -1464,7 +1702,7 @@ export async function apply(ctx, config) {
         const runPush = async () => {
           let sftp
           try {
-            sftp = await pool.sftp()
+            sftp = await b.pool.sftp()
           } catch (err) {
             throw new Error('sftp unavailable: ' + ((err && err.message) || err))
           }
@@ -1499,12 +1737,13 @@ export async function apply(ctx, config) {
         path: { type: 'string', description: 'Absolute remote path (default: current remote workspace)' },
       },
       output: textOut,
-      async execute(args) {
-        const p = args.path ? normalizeRemotePath(String(args.path)) : wsPath()
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_list_dir')
+        const p = args.path ? normalizeRemotePath(String(args.path)) : b.ws
         if (!p) throw new Error('rw_list_dir: no path and no remote workspace set')
         let list
         try {
-          const sftp = await pool.sftp()
+          const sftp = await b.pool.sftp()
           list = await sftp.readdir(p)
         } catch (err) {
           throw new Error('rw_list_dir: ' + ((err && err.message) || err))
@@ -1535,10 +1774,11 @@ export async function apply(ctx, config) {
         path: { type: 'string', required: true, description: 'Absolute remote path' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_stat')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p) throw new Error('rw_stat: path is required')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         let st
         try {
           st = await sftp.stat(p)
@@ -1569,14 +1809,15 @@ export async function apply(ctx, config) {
         encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_read_file')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p) throw new Error('rw_read_file: path is required')
         const maxLines = Math.min(Math.max(Number(args.maxLines) || 2000, 1), 10000)
         let from = Math.max(Number(args.startLine) || 1, 1)
         let to = Number(args.endLine) || 0
         if (!to || to - from + 1 > maxLines) to = from + maxLines - 1
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         let st
         try { st = await sftp.stat(p) } catch (err) { throw new Error('rw_read_file: ' + ((err && err.message) || err)) }
         if (config.maxFileBytes > 0 && st.size > config.maxFileBytes) {
@@ -1609,16 +1850,17 @@ export async function apply(ctx, config) {
         encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
       },
       output: okOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_write_file')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_write_file: a file path is required')
         const content = String(args.content == null ? '' : args.content)
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         if (args.mkdir !== false) await mkdirRemoteDirs(sftp, remoteDirname(p))
         const buf = encodeText(content, args.encoding || config.encoding)
         await sftp.writeFile(p, buf)
         const bytes = buf.byteLength
-        audit('write_file', `write ${p} (${bytes}B)`, 0)
+        audit('write_file', `write ${p} (${bytes}B)`, 0, b)
         return { ok: true, bytes, text: `wrote ${bytes} bytes to ${p}` }
       },
     }),
@@ -1635,13 +1877,14 @@ export async function apply(ctx, config) {
         encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
       },
       output: okOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_edit')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_edit: a file path is required')
         const oldS = String(args.old ?? '')
         const newS = String(args.new ?? '')
         if (oldS === '') throw new Error('rw_edit: old text must not be empty')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         const st0 = await sftp.stat(p)
         const buf = await sftp.readFile(p)
         const content = decodeBuf(buf, args.encoding || config.encoding)
@@ -1665,7 +1908,7 @@ export async function apply(ctx, config) {
           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))
-        audit('edit', `edit ${p} (${n} occurrence(s))`, 0)
+        audit('edit', `edit ${p} (${n} occurrence(s))`, 0, b)
         return { ok: true, bytes: Buffer.byteLength(out), text: `edited ${p}: replaced ${n} occurrence(s)` }
       },
     }),
@@ -1680,16 +1923,17 @@ export async function apply(ctx, config) {
         encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
       },
       output: okOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_append')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_append: a file path is required')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         let existing = ''
         try { existing = decodeBuf(await sftp.readFile(p), args.encoding || config.encoding) } catch { /* new file */ }
         const content = existing + String(args.content ?? '')
         await sftp.writeFile(p, encodeText(content, args.encoding || config.encoding))
         const bytes = Buffer.byteLength(content)
-        audit('append', `append ${p}`, 0)
+        audit('append', `append ${p}`, 0, b)
         return { ok: true, bytes, text: `appended to ${p} (now ${bytes} bytes)` }
       },
     }),
@@ -1702,12 +1946,13 @@ export async function apply(ctx, config) {
         path: { type: 'string', required: true, description: 'Absolute remote directory path' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_mkdir')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_mkdir: a directory path is required')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         await mkdirRemoteDirs(sftp, p)
-        audit('mkdir', `mkdir ${p}`, 0)
+        audit('mkdir', `mkdir ${p}`, 0, b)
         return { text: `created ${p}` }
       },
     }),
@@ -1721,20 +1966,21 @@ export async function apply(ctx, config) {
         recursive: { type: 'boolean', description: 'Recursively delete a directory (default false)' },
       },
       output: okOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_remove')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_remove: a path is required')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         const st = await sftp.stat(p).catch(() => null)
         if (!st) return { ok: false, text: `not found: ${p}` }
         if (st.isDirectory && st.isDirectory()) {
           if (!args.recursive) throw new Error(`rw_remove: ${p} is a directory — pass recursive=true to delete its tree`)
           const removed = await removeRemoteTree(sftp, p)
-          audit('remove', `remove -r ${p}`, 0)
+          audit('remove', `remove -r ${p}`, 0, b)
           return { ok: true, text: `removed ${removed} entries under ${p}` }
         }
         await sftp.unlink(p)
-        audit('remove', `remove ${p}`, 0)
+        audit('remove', `remove ${p}`, 0, b)
         return { ok: true, text: `removed ${p}` }
       },
     }),
@@ -1748,14 +1994,15 @@ export async function apply(ctx, config) {
         dest: { type: 'string', required: true, description: 'Destination absolute remote path' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_move')
         const p = normalizeRemotePath(String(args.path || ''))
         const d = normalizeRemotePath(String(args.dest || ''))
         if (!p || !d || p === '/') throw new Error('rw_move: both path and dest are required')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         await mkdirRemoteDirs(sftp, remoteDirname(d))
         await sftp.rename(p, d)
-        audit('move', `move ${p} → ${d}`, 0)
+        audit('move', `move ${p} → ${d}`, 0, b)
         return { text: `moved ${p} → ${d}` }
       },
     }),
@@ -1771,14 +2018,20 @@ export async function apply(ctx, config) {
         env: { type: 'object', additionalProperties: true, description: 'Extra environment variables (string values)' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_exec')
         const cmd = String(args.command || '')
         if (!cmd) throw new Error('rw_exec: command is required')
-        const ws = wsPath()
+        const ws = b.ws
         const cwd = args.cwd ? normalizeRemotePath(String(args.cwd)) : (ws || '')
         let full = cmd
         if (cwd) {
-          if (pool.platform === 'windows' && pool.gitBashPath) {
+          // Detect before choosing the cwd form: a per-machine pool starts
+          // undetected, and reading `platform` first would skip the Git Bash
+          // mount-path rewrite on the first command sent to a Windows host.
+          // detect() is cached and idempotent, so this costs one probe per pool.
+          try { await b.pool.detect() } catch { /* probe failed → fall through to the POSIX form */ }
+          if (b.pool.platform === 'windows' && b.pool.gitBashPath) {
             // Git Bash terminal: cd in the /c/Users/… mount form
             full = `cd ${shq(toShellPath(cwd))} && ${cmd}`
           } else if (!cwd.includes('\\')) {
@@ -1786,8 +2039,8 @@ export async function apply(ctx, config) {
           }
         }
         try {
-          const res = await pool.exec(full, { timeoutMs: config.commandTimeoutMs, pty: !!args.pty, env: args.env })
-          audit('exec', cmd, res.code)
+          const res = await b.pool.exec(full, { timeoutMs: config.commandTimeoutMs, pty: !!args.pty, env: args.env })
+          audit('exec', cmd, res.code, b)
           const parts = []
           if (res.stdout) parts.push(res.stdout.replace(/\s+$/, ''))
           if (res.stderr) parts.push('-- stderr --\n' + res.stderr.replace(/\s+$/, ''))
@@ -1797,7 +2050,7 @@ export async function apply(ctx, config) {
           else if (res.code !== 0) text += `\n[exit code: ${res.code}]`
           return { text }
         } catch (err) {
-          throw new Error(friendlyMessage(err, { host: config.host, port: config.port }))
+          throw new Error(friendlyMessage(err, { host: b.host, port: b.port }))
         }
       },
     }),
@@ -1815,10 +2068,11 @@ export async function apply(ctx, config) {
         maxMatches: { type: 'integer', description: 'Max matches to return (default 500)' },
       },
       output: textOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireBinding(exec, 'rw_search')
         const pattern = String(args.pattern || '')
         if (!pattern) throw new Error('rw_search: pattern is required')
-        const ws = wsPath()
+        const ws = b.ws
         const dir = args.path ? normalizeRemotePath(String(args.path)) : (ws || '')
         if (!dir) throw new Error('rw_search: no path and no remote workspace set')
         let regex
@@ -1827,7 +2081,7 @@ export async function apply(ctx, config) {
         } catch (err) {
           throw new Error('rw_search: bad pattern: ' + ((err && err.message) || err))
         }
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         const maxMatches = Math.min(Math.max(Number(args.maxMatches) || 500, 1), 2000)
         const matcher = ignoreMatcher()
         const { matches, scanned, truncated } = await searchTree(sftp, dir, {
@@ -1854,17 +2108,18 @@ export async function apply(ctx, config) {
         localPath: { type: 'string', description: 'Local destination (default: the workspace mirror, preserving the relative path)' },
       },
       output: okOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_download')
         const p = normalizeRemotePath(String(args.path || ''))
         if (!p || p === '/') throw new Error('rw_download: a remote file path is required')
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         let local
         if (args.localPath) {
           local = path.resolve(String(args.localPath))
         } else {
-          const ws = wsPath()
+          const ws = b.ws
           if (!ws) throw new Error('rw_download: no remote workspace set — pass localPath explicitly')
-          const base = mirrorDirFor(ws, config.host, config.username, config.port)
+          const base = mirrorDirFor(ws, b.host, b.username, b.port)
           const rel = p.startsWith(ws) ? p.slice(ws.length).replace(/^\/+/, '') : p.slice(1)
           local = path.join(base, rel)
         }
@@ -1888,16 +2143,17 @@ export async function apply(ctx, config) {
         path: { type: 'string', required: true, description: 'Absolute remote destination path' },
       },
       output: okOut,
-      async execute(args) {
+      async execute(args, exec) {
+        const b = requireMachine(exec, 'rw_upload')
         const rp = normalizeRemotePath(String(args.path || ''))
         const lp = String(args.localPath || '')
         if (!rp || rp === '/' || !lp) throw new Error('rw_upload: both localPath and a remote path are required')
         if (!existsSync(lp)) throw new Error(`rw_upload: local file not found: ${lp}`)
-        const sftp = await pool.sftp()
+        const sftp = await b.pool.sftp()
         await mkdirRemoteDirs(sftp, remoteDirname(rp))
         const st = statSync(lp)
         await sftp.fastPut(lp, rp)
-        audit('upload', `upload ${lp} → ${rp}`, 0)
+        audit('upload', `upload ${lp} → ${rp}`, 0, b)
         return { ok: true, bytes: st.size, text: `uploaded ${st.size} bytes from ${lp} → ${rp}` }
       },
     }),
@@ -1944,12 +2200,17 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_disconnect',
       description:
-        'Close the current SSH connection to the remote host, releasing the persistent pool (and stopping all active port forwards). Useful to rotate connections or after a long idle.',
+        "Close this session's SSH connection to its remote host, releasing the persistent pool. Useful to rotate a connection or after a long idle. Sessions bound to other machines keep their own connections.",
       parameters: {},
       output: okOut,
-      async execute() {
-        pool.close()
-        return { ok: true, text: 'disconnected (forwards stopped)' }
+      async execute(_args, exec) {
+        // Close the connection THIS session actually uses: closing the
+        // active-machine pool instead would look like a no-op to a bound
+        // session while disconnecting whichever machine happened to be active.
+        const b = bindingFor(exec)
+        b.pool.close()
+        if (!b.bound) return { ok: true, text: 'disconnected the active machine (forwards stopped)' }
+        return { ok: true, text: `disconnected ${b.username}@${b.host}:${b.port} for this session` }
       },
     }),
   ]
@@ -1974,14 +2235,21 @@ 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 } = resolveMirrorForLocal(cwd)
+      const { remotePath, machine } = 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
+      // states a host/path combination that may not exist (issue #25).
+      const who = machine
+        ? `${machine.username || 'user'}@${machine.host}`
+        : `${config.username || 'user'}@${config.host}`
+      const platform = machine ? poolForMachine(machine).platform : pool.platform
       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(', ')}`
       return (
         '## Remote workspace\n' +
-        `Current remote workspace: ${config.username || 'user'}@${config.host}:${toDisplayPath(remotePath, pool.platform)}\n` +
+        `Current remote workspace: ${who}:${toDisplayPath(remotePath, platform)}\n` +
         'Use the rw_* tools (rw_list_dir / rw_read_file / rw_write_file / rw_edit / rw_exec / rw_search / rw_sync / rw_push) to inspect and act on files on the remote host. Treat this directory as the working root for this task.' +
         extra
       )