dsh-remote 0.8.21 → 0.8.23

package/lib/index.js

@@ -33,7 +33,8 @@ import {
 import { createHostKeyGuard, isHostKeyKnown as _isHostKeyKnown } from './hostkey.js'
 import { compileIgnore, DEFAULT_IGNORE } from './ignore.js'
 import { friendlyMessage } from './errors.js'
-import { importableEntries, sshConfigPath, readSshConfigText } from './sshconfig.js'
+import { importableEntries, sshConfigPath, readSshConfigText, resolveMachineSshConfig } from './sshconfig.js'
+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 { searchRemote } from './search.js'
@@ -45,7 +46,7 @@ import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeM
 import { registerHttpTransports } from './http-transport.js'
 import { SshPool } from './pool.js'
 import { createFsRoutes } from './routes-fs.js'
-import { removeRemoteTree } from './remote-fs.js'
+import { listDirStructured, removeRemoteTree } from './remote-fs.js'
 
 export const name = 'dsh-remote'
 
@@ -107,6 +108,21 @@ export const Config = z.object({
   auditLog: z.boolean().default(true),
   /** Text encoding for remote file reads/writes (utf-8 default; gbk etc.). */
   encoding: z.string().default('utf-8'),
+  /** Remote `@` completion (issue #39). When on, a session whose workspace is a
+   * dsh-remote mirror lists the REMOTE tree for `@` (over SFTP, bounded) instead
+   * of the local mirror — which `ensureMirror()` leaves empty until a sync, so
+   * `@` used to find nothing at all. Sessions on a local workspace are
+   * untouched, and a host that cannot be reached falls back to the mirror. */
+  fileReference: z.boolean().default(true),
+  /** Max `@` candidates rendered for one query (mirrors the local provider). */
+  fileReferenceMaxResults: z.number().step(1).min(1).default(20),
+  /** Max entries retained in the remote `@` index of one workspace. */
+  fileReferenceMaxEntries: z.number().step(1).min(1).default(3000),
+  /** Directory basenames the remote `@` traversal skips. */
+  fileReferenceExcludedDirectories: z.array(z.string()).default([...DEFAULT_EXCLUDED_DIRECTORIES]),
+  /** Wall-clock budget (ms) for one remote `@` index pass; on expiry the
+   *  partial index answers rather than making the caret wait. */
+  fileReferenceTimeoutMs: z.number().step(1).min(200).default(4000),
   /** Update mode: `manual` (default) only checks when asked; `auto` checks on
    * load and periodically, applying a newer npm release automatically;
    * `off` disables version checks entirely. (schemastery 3.18 has no .enum —
@@ -154,14 +170,16 @@ function mirrorDirFor(remotePath, host, user, port) {
   return path.join(root, base + '-' + shortHash(norm))
 }
 
-/** Create the local mirror dir + a meta file describing its remote origin. */
-function ensureMirror(remotePath, host, user, port) {
+/** Create the local mirror dir + a meta file describing its remote origin.
+ *  `extra.alias` records the ~/.ssh/config alias a machine was saved as (issue
+ *  #38), so the mirror keeps resolving to its machine even if the alias's
+ *  HostName/user/port change in that file afterwards. */
+function ensureMirror(remotePath, host, user, port, extra = {}) {
   const dir = mirrorDirFor(remotePath, host, user, port)
   mkdirSync(dir, { recursive: true })
-  writeFileSync(
-    path.join(dir, '.dsh-remote-meta.json'),
-    JSON.stringify({ host, port, username: user, remotePath: normalizeRemotePath(remotePath), createdAt: new Date().toISOString() }, null, 2),
-  )
+  const meta = { host, port, username: user, remotePath: normalizeRemotePath(remotePath), createdAt: new Date().toISOString() }
+  if (extra.alias) meta.alias = String(extra.alias)
+  writeFileSync(path.join(dir, '.dsh-remote-meta.json'), JSON.stringify(meta, null, 2))
   return dir
 }
 
@@ -245,16 +263,83 @@ export async function apply(ctx, config) {
   const machines = store.list
   const machineIndex = (id) => machines.findIndex((m) => m.id === id)
 
+  // ── ssh-config aliases (issue #38) ────────────────────────────────────────
+  //
+  // A machine may be saved as an ALIAS (`useSshConfig: true`, `host` = the Host
+  // line of ~/.ssh/config). The registry then holds NO HostName/user/port/key —
+  // every connect resolves the alias against the config file as it is right now
+  // (VSCode Remote-SSH behaviour). The text is memoised for a couple of seconds
+  // so one request that resolves several machines reads the file once, while an
+  // edit to ~/.ssh/config still lands almost immediately.
+  let sshConfigCache = { text: '', at: 0 }
+  const sshConfigText = () => {
+    const now = Date.now()
+    if (now - sshConfigCache.at > 2000) sshConfigCache = { text: readSshConfigText(), at: now }
+    return sshConfigCache.text
+  }
+
+  /**
+   * A machine's CONNECT identity: alias machines are resolved through
+   * ~/.ssh/config; every other machine is returned untouched. The returned
+   * record keeps the registry fields (id, password, credentialBackend, …) so
+   * keychain lookups and the settings UI keep working.
+   */
+  const loggedSshWarnings = new Map()
+  const withSshConfig = (m) => {
+    // Short-circuit BEFORE reading ~/.ssh/config: a deployment with no alias
+    // machine must never touch that file, and the 2s text memo must not be
+    // primed by unrelated machines.
+    if (!m || !m.useSshConfig) return m
+    const resolved = resolveMachineSshConfig(m, { text: sshConfigText() })
+    if (!resolved) return m
+    // Warn once per distinct warning set: this runs on every tool call, and an
+    // unmatched alias would otherwise fill the log with the same line.
+    const signature = resolved.warnings.join(' | ')
+    if (signature && loggedSshWarnings.get(resolved.alias) !== signature) {
+      loggedSshWarnings.set(resolved.alias, signature)
+      try {
+        const logger = typeof ctx.get === 'function' ? ctx.get('logger') : undefined
+        if (logger && typeof logger.warn === 'function') {
+          logger.warn(`[dsh-remote] ssh-config alias "${resolved.alias}": ${resolved.warnings.join(' ')}`)
+        }
+      } catch { /* logging is best-effort */ }
+    }
+    return {
+      ...m,
+      sshAlias: resolved.alias,
+      sshConfigMatched: resolved.matched,
+      sshConfigWarnings: resolved.warnings,
+      host: resolved.host,
+      port: resolved.port,
+      username: resolved.username || m.username,
+      privateKeyPath: resolved.privateKeyPath || '',
+      proxy: resolved.proxy,
+    }
+  }
+
+  /** The alias a machine was saved as ('' for a machine with literal values). */
+  const aliasOf = (m) => (m && m.sshAlias) || (m && m.useSshConfig ? String(m.host || '') : '')
+
+  /** Machines as the settings UI sees them: secrets stripped, plus the
+   *  ~/.ssh/config resolution of an alias machine so a row can show where the
+   *  alias actually points without duplicating those values in the registry
+   *  (issue #38). */
+  const machinesForClient = () => machines.map((m) => ({
+    ...sanitizeMachine(m),
+    // Read ~/.ssh/config only when a machine actually uses an alias.
+    sshConfigResolved: m.useSshConfig ? resolveMachineSshConfig(m, { text: sshConfigText() }) : null,
+  }))
+
   /** The machine the pool is currently bound to: an ephemeral tool connection
    * (rw_connect save:false) wins, then the stored current, then config default. */
   let ephemeral = null
   const activeMachine = () => {
-    if (ephemeral) return ephemeral
+    if (ephemeral) return withSshConfig(ephemeral)
     if (store.currentId) {
       const i = machineIndex(store.currentId)
-      if (i >= 0) return machines[i]
+      if (i >= 0) return withSshConfig(machines[i])
     }
-    if (config.host) return { id: machineId(), name: config.host, host: config.host, port: config.port, username: config.username, password: config.password, privateKeyPath: config.privateKeyPath, passphrase: config.passphrase }
+    if (config.host) return withSshConfig({ id: machineId(), name: config.host, host: config.host, port: config.port, username: config.username, password: config.password, privateKeyPath: config.privateKeyPath, passphrase: config.passphrase })
     return null
   }
   const currentMachine = activeMachine
@@ -275,18 +360,47 @@ export async function apply(ctx, config) {
     return machinePassword(m)
   }
 
+  /** The identity fields pool.setTarget diffs. Used to snapshot the diff
+   *  baseline BEFORE applyMachine mutates the shared config in place. */
+  const targetFields = (c) => ({
+    host: c.host, port: c.port, username: c.username,
+    password: c.password, privateKeyPath: c.privateKeyPath,
+    passphrase: c.passphrase, workspace: c.workspace,
+    useAgent: c.useAgent, keyboardInteractive: c.keyboardInteractive,
+    proxy: c.proxy, hostKeyMode: c.hostKeyMode,
+  })
+
+  /** Fingerprint of the machine record last applied to the shared pool config.
+   * Re-applying an identical record is a no-op: the picker posts /current before
+   * every /ls and used to rewrite the registry + re-read credentials + re-point
+   * the pool on every autocomplete keystroke. A record change (settings edit)
+   * changes the fingerprint, so the next /current re-applies it. The value is
+   * maintained INSIDE applyActiveMachine / clearActiveMachine (not in
+   * setCurrent) so every apply path — boot restore, rw_connect save:true,
+   * POST /current — keeps the "fingerprint == applied" invariant without extra
+   * bookkeeping. */
+  let lastAppliedMachine = ''
+
+  /** Fingerprint of the registry record the shared config is bound to ('' when
+   *  the binding is ephemeral or no machine is current). */
+  const appliedFingerprint = () => {
+    if (ephemeral || !store.currentId) return ''
+    const i = machineIndex(store.currentId)
+    return i >= 0 ? JSON.stringify(machines[i]) : ''
+  }
+
   const applyActiveMachine = async () => {
     const m = activeMachine()
     if (!m || !m.host) return
     const pw = await machinePassword(m)
+    // Snapshot the diff baseline BEFORE applyMachine mutates the shared config
+    // IN PLACE: pool.config IS this config object, so setTarget would otherwise
+    // compare the new values against themselves, find them equal and keep the
+    // OLD connection alive across a machine switch (issue #25 hazard).
+    const previous = targetFields(config)
     applyMachine(config, { ...m, password: pw || m.password || '' })
-    pool.setTarget({
-      host: config.host, port: config.port, username: config.username,
-      password: config.password, privateKeyPath: config.privateKeyPath,
-      passphrase: config.passphrase, workspace: config.workspace,
-      useAgent: config.useAgent, keyboardInteractive: config.keyboardInteractive,
-      proxy: config.proxy, hostKeyMode: config.hostKeyMode,
-    })
+    pool.setTarget(targetFields(config), previous)
+    lastAppliedMachine = appliedFingerprint()
   }
 
   // ── per-machine SSH pools (session-bound) ─────────────────────────────────
@@ -333,12 +447,25 @@ export async function apply(ctx, config) {
    *  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 || ''))
+   *  connection would resolve to an empty-credential pool and fail to connect.
+   *
+   *  An ssh-config ALIAS machine (issue #38) is matched through its RESOLVED
+   *  identity, and directly by the alias the mirror recorded — so a mirror keeps
+   *  resolving to its machine even after a HostName/port change in ~/.ssh/config,
+   *  which is the whole point of not copying those values into the registry. */
+  const identityOf = (m) => {
+    const r = withSshConfig(m)
+    return { host: r.host, port: Number(r.port) || 22, username: r.username || '' }
+  }
+  const identityMatches = (m, { host, port, username }) => {
+    if (!m) return false
+    const id = identityOf(m)
+    return id.host === host && id.port === Number(port) && id.username === (username || '')
+  }
+  const machineRecordFor = ({ host, port, username, alias }) =>
+    (identityMatches(ephemeral, { host, port, username }) ? ephemeral : null)
+    || (alias ? machines.find((m) => aliasOf(m) === alias) : null)
+    || machines.find((m) => identityMatches(m, { host, port, username }))
     || null
 
   /**
@@ -348,47 +475,89 @@ export async function apply(ctx, config) {
    */
   const poolForMachine = (target) => {
     const key = poolKey(target)
+    // `rec` is the registry record (raw); `eff` is its CONNECT identity, with an
+    // ssh-config alias resolved (issue #38). For an alias whose HostName/USER/port
+    // changed since the mirror was created, the RESOLVED identity wins over the
+    // mirror-recorded one — that is what makes an edit to ~/.ssh/config take
+    // effect for an existing session instead of dialing the stale address.
     const rec = machineRecordFor(target)
+    const eff = rec ? withSshConfig(rec) : null
+    const host = (eff && eff.host) || target.host
+    const port = Number((eff && eff.port) || target.port) || 22
+    const username = (eff && eff.username) || target.username || 'root'
     const existing = machinePools.get(key)
     if (existing) {
       syncTunables(existing.config)
+      // Re-point a live pool whose resolved identity moved (setTarget closes the
+      // connection, so only do it when something actually changed).
+      if (existing.config.host !== host || Number(existing.config.port) !== port || (existing.config.username || '') !== username) {
+        existing.setTarget({ host, port, username })
+      }
       // 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
+      if (eff) {
+        existing.config.password = eff.password || ''
+        existing.config.privateKeyPath = eff.privateKeyPath || ''
+        existing.config.passphrase = eff.passphrase || ''
+        existing.config.useAgent = !!eff.useAgent
+        existing.config.keyboardInteractive = !!eff.keyboardInteractive
+        existing.config.proxy = eff.proxy || undefined
+        existing.config.hostKeyMode = eff.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,
+      host,
+      port,
+      username,
+      password: (eff && eff.password) || '',
+      privateKeyPath: (eff && eff.privateKeyPath) || '',
+      passphrase: (eff && eff.passphrase) || '',
+      useAgent: eff ? !!eff.useAgent : !!config.useAgent,
+      keyboardInteractive: eff ? !!eff.keyboardInteractive : !!config.keyboardInteractive,
+      proxy: (eff && eff.proxy) || undefined,
+      hostKeyMode: (eff && eff.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, { knownHostsFile })
     // Keychain-backed passwords resolve against THIS pool's machine record.
-    created.passwordResolver = async () => machinePassword(rec || { id: '', password: poolConfig.password })
+    created.passwordResolver = async () => machinePassword(eff || { id: '', password: poolConfig.password })
     machinePools.set(key, created)
     return created
   }
 
+  /**
+   * Re-assert the ACTIVE machine that a machine-scoped request names.
+   *
+   * The workspace picker (and the settings page's workspace flow) acts on the
+   * shared active pool, but it remembers its own `machineId` locally. Nothing
+   * on `/mirror` / `/home` / `/fs` used to carry that identity, so a switch
+   * performed by ANOTHER actor between the picker's last fetch and its commit —
+   * the settings page's "set as current", or an `rw_connect` in another agent
+   * session — silently redirected the commit onto that other machine. Before
+   * this PR the picker re-posted /current on every keystroke, which masked the
+   * window; the per-keystroke reconnect fix removes that accident. Let the
+   * request state its intent so the host can honour it atomically instead.
+   *
+   * An absent / empty `machineId` keeps the old behaviour (the caller is
+   * machine-scoped through the active pool by design). An UNKNOWN id is
+   * refused rather than ignored: quietly mirroring onto whichever machine
+   * happens to be active is exactly the hazard this closes.
+   *
+   * @returns {Promise<boolean>} false when the request was already answered.
+   */
+  const applyRequestedMachine = async (body, res) => {
+    const id = String((body && body.machineId) || '').trim()
+    if (!id) return true
+    if (await setCurrent(id)) return true
+    sendJson(res, 404, { ok: false, error: `machine not found: ${id}` })
+    return false
+  }
+
   const setCurrent = async (id) => {
     if (!id) {
       // Explicit "active remote = none": saved machines stay in the registry
@@ -401,6 +570,11 @@ export async function apply(ctx, config) {
     }
     const i = machineIndex(id)
     if (i < 0) return false
+    // Idempotent: same machine, no ephemeral override, already applied → keep
+    // the registry file, the credentials cache and the live pool untouched.
+    // (The fingerprint is maintained by applyActiveMachine itself.)
+    const fingerprint = JSON.stringify(machines[i])
+    if (store.currentId === id && !ephemeral && config.host && lastAppliedMachine === fingerprint) return true
     store.currentId = id
     ephemeral = null
     saveMachines(machines, id)
@@ -413,7 +587,13 @@ export async function apply(ctx, config) {
    * tool fallback, but no machine workspace leaks into this session. */
   const clearActiveMachine = async () => {
     ephemeral = null
+    // Nothing is applied anymore — reset the applied-machine fingerprint too.
+    lastAppliedMachine = ''
     if (!config.host) return
+    // Snapshot the diff baseline BEFORE zeroing: pool.config IS this config
+    // object, so setTarget would otherwise see an already-zeroed config and
+    // keep the old connection alive ("active remote = none" must disconnect).
+    const previous = targetFields(config)
     // Clear host + workspace directly (applyMachine keeps the old workspace
     // when the incoming value is empty — it must not be used for a full reset).
     config.host = ''
@@ -421,7 +601,7 @@ export async function apply(ctx, config) {
     config.username = ''
     config.password = ''
     config.workspace = ''
-    pool.setTarget({ host: '', port: 22, username: '', workspace: '' })
+    pool.setTarget({ host: '', port: 22, username: '', workspace: '' }, previous)
     // Also stop any auto-push watcher bound to the old machine workspace.
     // (autoPushWatchers is declared later; read it lazily to avoid TDZ.)
     if (typeof autoPushWatchers !== 'undefined' && autoPushWatchers) {
@@ -682,6 +862,7 @@ export async function apply(ctx, config) {
           host: machine.host,
           username: machine.username,
           port: machine.port,
+          alias: machine.alias || '',
           mirrorDir,
           bound: true,
           local: false,
@@ -737,6 +918,7 @@ export async function apply(ctx, config) {
           host: machine.host,
           username: machine.username,
           port: machine.port,
+          alias: machine.alias || '',
           mirrorDir,
           bound: true,
           local: false,
@@ -824,7 +1006,7 @@ export async function apply(ctx, config) {
     // active — saved machines stay standby-only.
     sessionMode: sessionRemotePath() ? 'remote' : (store.currentId ? 'standby' : 'local'),
     sessionRemotePath: sessionRemotePath(),
-    machines: machines.map(sanitizeMachine),
+    machines: machinesForClient(),
     hostKeyMode: config.hostKeyMode === 'verify' || config.hostKeyMode === 'off' ? config.hostKeyMode : 'accept-new',
     hostKeyKnown: config.host ? isHostKeyKnown(config.host, config.port) : false,
     forwards: forwards.list(),
@@ -835,6 +1017,125 @@ export async function apply(ctx, config) {
     gitBash: pool.gitBashPath || '',
   })
 
+  // ── remote `@` completion (issue #39) ─────────────────────────────────────
+  //
+  // `@` candidates come from `ctx.fileReferences`, whose only shipped provider
+  // indexes the agent session's LOCAL cwd. A remote session's cwd is the (empty
+  // until synced) mirror, so `@` listed nothing. The seam is a single-owner
+  // service, so lib/file-reference.js WRAPS `fileReferences.list` and answers
+  // remote-bound sessions from the remote host over SFTP.
+  //
+  // Everything below is glue: which remote root an agent is bound to, and how a
+  // workspace-relative directory is listed over the machine's own pool.
+
+  /** Join a workspace-relative directory onto a remote root, segment by
+   *  segment, so the root's separator style is preserved on Windows hosts. */
+  const joinRemoteRel = (base, rel) => {
+    let out = base
+    for (const segment of String(rel || '').split('/')) {
+      if (!segment || segment === '.') continue
+      out = joinRemotePath(out, segment)
+    }
+    return out
+  }
+
+  const fileReferenceLog = (msg) => {
+    try {
+      const logger = typeof ctx.get === 'function' ? ctx.get('logger') : undefined
+      if (logger && typeof logger.warn === 'function') logger.warn('[dsh-remote] ' + msg)
+    } catch { /* logging is best-effort */ }
+  }
+
+  /** Providers, one per (machine, remote root): the index cache is expensive to
+   *  rebuild, so typing in the SAME workspace keeps reusing it. */
+  const fileReferenceProviders = new Map()
+  const FILE_REFERENCE_PROVIDER_CAP = 32
+
+  /**
+   * The remote discovery provider for one agent, or null when that agent is not
+   * a remote session (or the feature is off) — in which case the original local
+   * provider answers, unchanged.
+   */
+  const remoteFileReferenceFor = (agent) => {
+    // `=== false` rather than falsy: a partially-specified config (a scripted
+    // apply(), an older profile) must still get the remote listing, which is
+    // what the schema default promises.
+    if (config.fileReference === false) return null
+    const cwd = agent && agent.session && agent.session.header ? agent.session.header.cwd : ''
+    if (!cwd) return null
+    const { remotePath, machine } = resolveMirrorForLocal(String(cwd))
+    if (!remotePath || !machine) return null
+    const root = normalizeRemotePath(remotePath)
+    const key = poolKey(machine) + '\u0000' + root
+    const cached = fileReferenceProviders.get(key)
+    if (cached) return cached
+    const provider = createRemoteFileReference({
+      root,
+      // '' = the workspace root; every other value is a workspace-relative dir.
+      listDir: async (rel) => {
+        const p = poolForMachine(machine)
+        const sftp = await p.sftp()
+        const out = await listDirStructured(sftp, rel ? joinRemoteRel(root, rel) : root)
+        return out.items.map((item) => ({
+          name: item.name,
+          kind: item.type === 'dir' ? 'directory' : 'file',
+        }))
+      },
+      config: {
+        root,
+        maxResults: config.fileReferenceMaxResults,
+        maxEntries: config.fileReferenceMaxEntries,
+        excludedDirectories: config.fileReferenceExcludedDirectories,
+        timeoutMs: config.fileReferenceTimeoutMs,
+      },
+      onError: (err) => fileReferenceLog(`@ listing failed for ${machine.host}:${root}: ${(err && err.message) || err}`),
+    })
+    if (fileReferenceProviders.size >= FILE_REFERENCE_PROVIDER_CAP) {
+      const oldest = fileReferenceProviders.keys().next().value
+      try { fileReferenceProviders.get(oldest)?.dispose() } catch { /* already disposed */ }
+      fileReferenceProviders.delete(oldest)
+    }
+    fileReferenceProviders.set(key, provider)
+    return provider
+  }
+
+  const fileReferenceOverlay = installFileReferenceOverlay(ctx, {
+    resolve: remoteFileReferenceFor,
+    onError: (err) => fileReferenceLog(`@ completion overlay: ${(err && err.message) || err}`),
+  })
+  ctx.effect(() => () => {
+    try { fileReferenceOverlay?.dispose?.() } catch { /* already disposed */ }
+    for (const provider of fileReferenceProviders.values()) {
+      try { provider.dispose() } catch { /* already disposed */ }
+    }
+    fileReferenceProviders.clear()
+  }, 'dsh-remote.file-reference')
+
+  /**
+   * Resolve a PATH ARGUMENT a tool received against the session's remote
+   * workspace root when it is not already absolute (issue #39).
+   *
+   * An `@path` mention in a remote session is workspace-relative — the same
+   * shape the local provider produces — so `rw_read_file("src/main.c")` must
+   * mean `<remote workspace>/src/main.c`, not the filesystem root's `/src`.
+   * Absolute POSIX (`/a/b`), Windows (`D:\a`, `/D:/a`) and UNC (`\\host\share`)
+   * forms pass through normalizeRemotePath() unchanged, so behaviour for every
+   * existing caller is preserved. `..` segments collapse inside the joined path
+   * exactly as normalizeRemotePath() already did.
+   *
+   * @param {{ws: string}} b - the binding resolved for this call.
+   * @param {unknown} raw - the raw argument value.
+   * @returns {string} a normalized remote path.
+   */
+  const resolveRemoteArg = (b, raw) => {
+    const s = String(raw ?? '').trim()
+    const absolute = s.startsWith('/') || s.startsWith('\\\\') || /^[a-zA-Z]:[\\/]/.test(s)
+    if (absolute) return normalizeRemotePath(s)
+    const rel = s.replace(/^\.\//, '').replace(/^[\\/]+/, '')
+    if (!rel) return normalizeRemotePath(b.ws || '')
+    return normalizeRemotePath(b.ws ? joinRemoteRel(b.ws, rel.replace(/\\/g, '/')) : rel)
+  }
+
   // ── tools ─────────────────────────────────────────────────────────────────
 
   const textOut = {
@@ -902,19 +1203,21 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_connect',
       description:
-        'Connect SSH to a remote host for remote workspace work. Provide host (required), user, optional password or privateKeyPath/port. 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.',
+        'Connect SSH to a remote host for remote workspace work. Provide host (required), user, optional password or privateKeyPath/port. 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.',
       parameters: {
-        host: { type: 'string', required: true, description: 'Remote host IP or hostname' },
+        host: { type: 'string', required: true, description: 'Remote host IP or hostname (or a ~/.ssh/config alias with useSshConfig=true)' },
         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)' },
         privateKeyPath: { type: 'string', description: 'Absolute private-key path' },
+        useSshConfig: { type: 'boolean', description: 'Treat `host` as a ~/.ssh/config Host alias; resolve host/user/port/key/proxy from that file (issue #38)' },
         save: { type: 'boolean', description: 'Save this machine to the registry and make it current (default true)' },
       },
       output: textOut,
       async execute(args) {
         const host = String(args.host || '').trim()
         if (!host) throw new Error('rw_connect: host is required')
+        const useSshConfig = !!args.useSshConfig
         const user = args.username || config.username || 'root'
         const port = Number(args.port) || undefined
         const rec = {
@@ -924,12 +1227,18 @@ export async function apply(ctx, config) {
           password: args.password !== undefined ? String(args.password) : '',
           privateKeyPath: args.privateKeyPath || '',
         }
+        if (useSshConfig) rec.useSshConfig = true
+        // An alias connection must dial the RESOLVED identity (~/.ssh/config),
+        // while the registry keeps the alias itself.
+        const eff = useSshConfig ? withSshConfig(rec) : rec
+        const effUser = eff.username || user
+        const effPort = Number(eff.port) || port || 22
         if (args.save !== false) {
           // Upsert into the registry and make it the current machine so the
           // settings UI and the tools always agree on who is active.
           const i = machines.findIndex((m) => m.host === rec.host && m.username === rec.username && Number(m.port) === rec.port)
           if (i >= 0) {
-            machines[i] = { ...machines[i], ...rec, id: machines[i].id, password: rec.password || machines[i].password || '' }
+            machines[i] = { ...machines[i], ...rec, useSshConfig, id: machines[i].id, password: rec.password || machines[i].password || '' }
             store.currentId = machines[i].id
             saveMachines(machines, store.currentId)
           } else {
@@ -939,25 +1248,35 @@ export async function apply(ctx, config) {
             saveMachines(machines, store.currentId)
           }
           ephemeral = null
+          // rw_connect means "connect now": force a fresh dial even for an
+          // identical target (setTarget alone would reuse a possibly half-open
+          // cached client — same reconnect-probe reasoning as /connect).
+          pool.invalidate()
           await applyActiveMachine()
         } else {
           ephemeral = { id: machineId(), name: host, ...rec }
+          // rw_connect means "connect now": force a fresh dial even for an
+          // identical target (setTarget alone would reuse a possibly half-open
+          // cached client — same reconnect-probe reasoning as /connect).
+          pool.invalidate()
           pool.setTarget({
-            host, port: port || 22, username: user,
-            password: rec.password, privateKeyPath: rec.privateKeyPath,
+            host: eff.host, port: effPort, username: effUser,
+            password: rec.password, privateKeyPath: eff.privateKeyPath || '',
+            proxy: eff.proxy,
             workspace: config.workspace,
           })
         }
         try {
           const res = await pool.exec('echo ok', { timeoutMs: 8000 })
           if (res.code !== 0 && !res.stdout) {
-            audit('connect', `connect ${user}@${host}:${port || 22}`, res.code)
+            audit('connect', `connect ${effUser}@${eff.host}:${effPort}`, res.code)
             return { text: 'connect failed: ' + (res.stderr || 'exit ' + res.code) }
           }
-          audit('connect', `connect ${user}@${host}:${port || 22}`, 0)
-          return { text: `Connected to ${host} as ${config.username}.\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
+          audit('connect', `connect ${effUser}@${eff.host}:${effPort}`, 0)
+          const via = useSshConfig ? `\n(ssh-config alias "${host}" → ${effUser}@${eff.host}:${effPort}` + (eff.sshConfigWarnings && eff.sshConfigWarnings.length ? `; ${eff.sshConfigWarnings.join(' ')}` : '') + ')' : ''
+          return { text: `Connected to ${eff.host} as ${config.username}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
         } catch (err) {
-          throw new Error(friendlyMessage(err, { host, port }))
+          throw new Error(friendlyMessage(err, { host: eff.host, port: effPort }))
         }
       },
     }),
@@ -988,7 +1307,7 @@ export async function apply(ctx, config) {
         // 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)
+        const local = ensureMirror(p, b.host, b.username, b.port, { alias: b.alias || "" })
         startAutoPush(local)
         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.`,
@@ -1108,7 +1427,7 @@ export async function apply(ctx, config) {
       output: textOut,
       async execute(args, exec) {
         const b = requireBinding(exec, 'rw_list_dir')
-        const p = args.path ? normalizeRemotePath(String(args.path)) : b.ws
+        const p = args.path ? resolveRemoteArg(b, args.path) : b.ws
         if (!p) throw new Error('rw_list_dir: no path and no remote workspace set')
         let list
         try {
@@ -1145,7 +1464,7 @@ export async function apply(ctx, config) {
       output: textOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_stat')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, args.path)
         if (!p) throw new Error('rw_stat: path is required')
         const sftp = await b.pool.sftp()
         let st
@@ -1180,7 +1499,7 @@ export async function apply(ctx, config) {
       output: textOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_read_file')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, 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)
@@ -1221,7 +1540,7 @@ export async function apply(ctx, config) {
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_write_file')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, 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 b.pool.sftp()
@@ -1248,7 +1567,7 @@ export async function apply(ctx, config) {
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_edit')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, 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 ?? '')
@@ -1294,7 +1613,7 @@ export async function apply(ctx, config) {
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_append')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, args.path)
         if (!p || p === '/') throw new Error('rw_append: a file path is required')
         const sftp = await b.pool.sftp()
         let existing = ''
@@ -1317,7 +1636,7 @@ export async function apply(ctx, config) {
       output: textOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_mkdir')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, args.path)
         if (!p || p === '/') throw new Error('rw_mkdir: a directory path is required')
         const sftp = await b.pool.sftp()
         await mkdirRemoteDirs(sftp, p)
@@ -1337,7 +1656,7 @@ export async function apply(ctx, config) {
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_remove')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, args.path)
         if (!p || p === '/') throw new Error('rw_remove: a path is required')
         const sftp = await b.pool.sftp()
         const st = await sftp.stat(p).catch(() => null)
@@ -1365,8 +1684,8 @@ export async function apply(ctx, config) {
       output: textOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_move')
-        const p = normalizeRemotePath(String(args.path || ''))
-        const d = normalizeRemotePath(String(args.dest || ''))
+        const p = resolveRemoteArg(b, args.path)
+        const d = resolveRemoteArg(b, args.dest)
         if (!p || !d || p === '/') throw new Error('rw_move: both path and dest are required')
         const sftp = await b.pool.sftp()
         await mkdirRemoteDirs(sftp, remoteDirname(d))
@@ -1392,7 +1711,7 @@ export async function apply(ctx, config) {
         const cmd = String(args.command || '')
         if (!cmd) throw new Error('rw_exec: command is required')
         const ws = b.ws
-        const cwd = args.cwd ? normalizeRemotePath(String(args.cwd)) : (ws || '')
+        const cwd = args.cwd ? resolveRemoteArg(b, args.cwd) : (ws || '')
         let full = cmd
         if (cwd) {
           // Detect before choosing the cwd form: a per-machine pool starts
@@ -1442,7 +1761,7 @@ export async function apply(ctx, config) {
         const pattern = String(args.pattern || '')
         if (!pattern) throw new Error('rw_search: pattern is required')
         const ws = b.ws
-        const dir = args.path ? normalizeRemotePath(String(args.path)) : (ws || '')
+        const dir = args.path ? resolveRemoteArg(b, args.path) : (ws || '')
         if (!dir) throw new Error('rw_search: no path and no remote workspace set')
         let regex
         try {
@@ -1481,7 +1800,7 @@ export async function apply(ctx, config) {
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_download')
-        const p = normalizeRemotePath(String(args.path || ''))
+        const p = resolveRemoteArg(b, args.path)
         if (!p || p === '/') throw new Error('rw_download: a remote file path is required')
         const sftp = await b.pool.sftp()
         let local
@@ -1516,7 +1835,7 @@ export async function apply(ctx, config) {
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_upload')
-        const rp = normalizeRemotePath(String(args.path || ''))
+        const rp = resolveRemoteArg(b, 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}`)
@@ -1615,13 +1934,20 @@ export async function apply(ctx, config) {
         ? `${machine.username || 'user'}@${machine.host}`
         : `${config.username || 'user'}@${config.host}`
       const platform = machine ? poolForMachine(machine).platform : pool.platform
+      const shown = toDisplayPath(remotePath, 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(', ')}`
+      // 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.
       return (
         '## Remote workspace\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.' +
+        `Current remote workspace: ${who}:${shown}\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.\n' +
+        `\`@path\` mentions in this conversation name files under THAT remote root (\`@src/main.c\` = ${shown}/src/main.c). ` +
+        'The rw_* tools take such paths as workspace-relative and resolve them against this root. ' +
+        'The harness\'s built-in read/list tools only see the LOCAL mirror of this directory, which stays empty until rw_sync — use rw_read_file for remote files.' +
         extra
       )
     },
@@ -1931,6 +2257,12 @@ export async function apply(ctx, config) {
         let payload = {}
         try {
           payload = parseJsonObject(await readBody(req))
+          // This route is a reconnect PROBE ("Connect" button): with the
+          // unchanged-target no-op in setTarget, an identical target would
+          // reuse a possibly half-open cached client and the probe could hang.
+          // invalidate() is the design's forced-reconnect escape hatch — drop
+          // the cached client so the `echo ok` below always re-dials.
+          pool.invalidate()
           pool.setTarget({
             host: payload.host,
             port: payload.port,
@@ -1962,7 +2294,7 @@ export async function apply(ctx, config) {
           const okDir = await isRemoteDir(p)
           if (!okDir) return sendJson(res, 400, { ok: false, error: `not a directory: ${p}` })
           persistWorkspace(p)
-          const local = ensureMirror(p, config.host, config.username, config.port)
+          const local = ensureMirror(p, config.host, config.username, config.port, { alias: aliasOf(activeMachine()) })
           startAutoPush(local)
           return sendJson(res, 200, { ok: true, workspace: p, localMirror: local, ...status() })
         } catch (err) {
@@ -1980,9 +2312,14 @@ export async function apply(ctx, config) {
           const p = normalizeRemotePath(String(payload.path || ''))
           if (!p || p === '/') return sendJson(res, 400, { ok: false, error: 'path must be an absolute directory' })
           if (!config.host) return sendJson(res, 400, { ok: false, error: 'no remote host configured/connected — connect first' })
+          // The picker names the machine it was browsing. Re-assert it so a
+          // switch made elsewhere between the listing and this commit cannot
+          // mirror onto a machine the user never looked at (the picker sends
+          // /current only once per machine now, so nothing else re-applies it).
+          if (!(await applyRequestedMachine(payload, res))) return
           const okDir = await isRemoteDir(p)
           if (!okDir) return sendJson(res, 400, { ok: false, error: `not a directory (or unreachable): ${p}` })
-          const local = ensureMirror(p, config.host, config.username, config.port)
+          const local = ensureMirror(p, config.host, config.username, config.port, { alias: aliasOf(activeMachine()) })
           persistWorkspace(p)
           startAutoPush(local)
           return sendJson(res, 200, { ok: true, path: p, localMirror: local, ...status() })
@@ -2088,7 +2425,7 @@ export async function apply(ctx, config) {
       path: '/dsh-remote/machines',
       handler: async (req, res) => {
         if (req.method === 'GET') {
-          return sendJson(res, 200, { machines: machines.map(sanitizeMachine), currentId: store.currentId })
+          return sendJson(res, 200, { machines: machinesForClient(), currentId: store.currentId })
         }
         if (req.method === 'POST') {
           try {
@@ -2108,6 +2445,10 @@ export async function apply(ctx, config) {
                 id,
                 name: String(body.name || '').trim() || host,
                 host,
+                // Issue #38: an ALIAS machine stores only the Host line of
+                // ~/.ssh/config — HostName/user/port/key are resolved live at
+                // every connect instead of being copied into the registry.
+                useSshConfig: !!body.useSshConfig,
                 port: Number(body.port) || 22,
                 username: String(body.username || '').trim() || 'root',
                 password: '',
@@ -2162,7 +2503,7 @@ export async function apply(ctx, config) {
               return sendJson(res, 200, {
                 ok: true,
                 machine: sanitizeMachine(rec),
-                machines: machines.map(sanitizeMachine),
+                machines: machinesForClient(),
                 currentId: store.currentId,
                 ...(warning ? { warning, warningDetail } : {}),
               })
@@ -2186,7 +2527,7 @@ export async function apply(ctx, config) {
               } else {
                 saveMachines(machines, store.currentId)
               }
-              return sendJson(res, 200, { ok: true, machines: machines.map(sanitizeMachine), currentId: store.currentId })
+              return sendJson(res, 200, { ok: true, machines: machinesForClient(), currentId: store.currentId })
             }
             return sendJson(res, 400, { ok: false, error: 'unknown action' })
           } catch (err) {
@@ -2209,21 +2550,33 @@ export async function apply(ctx, config) {
         let body = {}
         try {
           body = parseJsonObject(await readBody(req))
+          // Issue #38: "test" on an ssh-config ALIAS resolves the alias first —
+          // the form holds the alias name, not the host it points at.
+          const aliasTarget = body.useSshConfig
+            ? resolveMachineSshConfig({
+                host: String(body.host || ''),
+                port: Number(body.port) || 22,
+                username: String(body.username || ''),
+                privateKeyPath: String(body.privateKeyPath || ''),
+                proxy: body.proxy,
+                useSshConfig: true,
+              }, { text: sshConfigText() })
+            : null
           const probe = new SshPool({
             ...config,
-            host: String(body.host || config.host),
-            port: Number(body.port) || config.port,
-            username: String(body.username || config.username),
+            host: aliasTarget ? aliasTarget.host : String(body.host || config.host),
+            port: aliasTarget ? aliasTarget.port : (Number(body.port) || config.port),
+            username: aliasTarget ? aliasTarget.username : String(body.username || config.username),
             password: String(body.password || ''),
-            privateKeyPath: String(body.privateKeyPath || config.privateKeyPath),
+            privateKeyPath: aliasTarget ? aliasTarget.privateKeyPath : String(body.privateKeyPath || config.privateKeyPath),
             passphrase: String(body.passphrase || ''),
-            proxy: body.proxy && body.proxy.host ? {
+            proxy: aliasTarget && aliasTarget.proxy ? aliasTarget.proxy : (body.proxy && body.proxy.host ? {
               host: String(body.proxy.host),
               port: Number(body.proxy.port) || 22,
               username: String(body.proxy.username || ''),
               password: String(body.proxy.password || ''),
               privateKeyPath: String(body.proxy.privateKeyPath || ''),
-            } : undefined,
+            } : undefined),
             connectTimeoutMs: Math.min(Math.max(Number(body.connectTimeoutMs) || config.connectTimeoutMs, 2000), 30000),
             commandTimeoutMs: 10000,
           }, { knownHostsFile })
@@ -2232,13 +2585,27 @@ export async function apply(ctx, config) {
           await probe.exec('true', { timeoutMs: 10000 })
           probe.close()
           const latencyMs = Date.now() - started
-          const mi = machines.findIndex((m) => m.host === probe.config.host && m.username === probe.config.username && Number(m.port) === probe.config.port)
+          // Alias-aware: the probe connects to the RESOLVED host, while the
+          // registry stores the alias, so matching must go through the identity.
+          const mi = machines.findIndex((m) => identityMatches(m, { host: probe.config.host, port: probe.config.port, username: probe.config.username }))
           if (mi >= 0) {
             machines[mi].lastConnectedAt = new Date().toISOString()
             machines[mi].latencyMs = latencyMs
             saveMachines(machines, store.currentId)
           }
-          return sendJson(res, 200, { ok: true, host: probe.config.host, user: probe.config.username, latencyMs, lastConnectedAt: new Date().toISOString(), platform: probe.platform, shell: probe.shellMode, gitBash: probe.gitBashPath || '' })
+          return sendJson(res, 200, {
+            ok: true,
+            host: probe.config.host,
+            user: probe.config.username,
+            latencyMs,
+            lastConnectedAt: new Date().toISOString(),
+            platform: probe.platform,
+            shell: probe.shellMode,
+            gitBash: probe.gitBashPath || '',
+            // Issue #38: tell the settings page where an alias resolved to (and
+            // anything the plugin could not honour, e.g. a multi-hop ProxyJump).
+            alias: aliasTarget ? { name: aliasTarget.alias, host: aliasTarget.host, port: aliasTarget.port, user: aliasTarget.username, warnings: aliasTarget.warnings } : null,
+          })
         } catch (err) {
           return sendJson(res, 200, { ok: false, error: friendlyMessage(err, { host: body.host, port: body.port }) })
         }
@@ -2379,6 +2746,11 @@ export async function apply(ctx, config) {
       handler: async (req, res) => {
         if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
         try {
+          const body = parseJsonObject(await readBody(req))
+          // The picker names the machine it is showing: re-assert it before
+          // answering, so a switch made elsewhere cannot make /home describe a
+          // different host than the tree the user is looking at.
+          if (!(await applyRequestedMachine(body, res))) return
           const out = await pool.exec('echo ~', { timeoutMs: Math.min(config.commandTimeoutMs, 5000) })
           const home = String(out.stdout || '').replace(/\s+/g, '').trim()
           if (!home) return sendJson(res, 200, { ok: true, home: null, hint: 'Windows 远程暂不支持 ~ 解析，请直接输入绝对路径' })