dsh-remote 0.8.73 → 0.8.74

package/lib/index.js

@@ -56,6 +56,7 @@ import { selfDir, diskVersion, LOADED_VERSION, gtVersion, fetchLatestVersion, ap
 import { sendHeartbeat, pseudonym, heartbeatUrl, hasPersistedId, installIdPath } from './telemetry.js'
 import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeMachine as _sanitizeMachine, applyMachine as _applyMachine, machineId as _machineId, normalizeMachineGroup, filterMachinesByGroup, resolveProbeCredentials } from './registry.js'
 import { registerHttpTransports } from './http-transport.js'
+import { createHostApi } from './host-api.js'
 import { SshPool, ActivePool, createPool } from './pool.js'
 import { isSystemOpenSshBackend, sshBinaryAvailable, resolveSshBinary } from './openssh.js'
 import { createFsRoutes } from './routes-fs.js'
@@ -283,6 +284,22 @@ export const Config = z.object({
    *  plaintext is the one outcome you did not ask for.
    *  `plain`: the pre-0.8.54 fallback (write it and warn). */
   credentialFallback: z.string().default('refuse'),
+  /** TUI integration layer (docs/tui.md): register the `/dsh-remote` scene,
+   *  the workspace provider and the `/dsh-remote` slash command when a
+   *  dsh-tui profile is present. `false` disables the whole layer — on a Web or
+   *  Desktop profile it already degrades to a no-op by soft-probing its seams. */
+  tui: z.boolean().default(true),
+  /** List each machine's recent workspaces in the TUI workspace picker. */
+  tuiProviderListRecent: z.boolean().default(true),
+  /** How many recent workspaces per machine the picker lists (1–20). */
+  tuiProviderRecentLimit: z.number().step(1).min(1).max(20).default(5),
+  /** Switch the session to a remote workspace right after adopting it in the
+   *  TUI scene. */
+  tuiAutoSwitchWorkspace: z.boolean().default(true),
+  /** Language for the TUI layer's own copy: `''` = auto (zh, or `en` when
+   *  `DSH_TUI_LANG=en`), `zh` / `en` pins it. The TUI's own screens keep their
+   *  own language; this only affects `/dsh-remote` and its toasts. */
+  tuiLang: z.string().default(''),
 })
 
 // ── shell / path helpers (pure implementations in lib/paths.js) ───────────
@@ -1447,6 +1464,63 @@ export async function apply(ctx, config) {
    *  another machine. Tool calls must never route through this — they resolve
    *  their own session through `bindingFor()`, which is authoritative. */
   const sessionsSvc = () => (ctx && typeof ctx.get === 'function' ? ctx.get('sessions') : null)
+
+  /** Whether one session is still open somewhere.
+   *
+   * In-process: the `sessions` service knows every live (including parked)
+   * session of THIS TUI, so the cleanup page can refuse to delete its own.
+   * Cross-process: DSH holds a kernel `flock` on `<session dir>/session.lock`
+   * for the life of the write handle, so a successful `lsof` names the holder.
+   * `deep: false` skips the spawn — list views call it for every row.
+   */
+  const isSessionLive = async (sessionId, dir, opts = {}) => {
+    try {
+      const live = sessionsSvc()
+      if (live && typeof live.get === 'function' && live.get(sessionId)) return true
+    } catch { /* no sessions service (minimal embedding) */ }
+    if (opts && opts.deep === true && process.platform !== 'win32') {
+      const lock = path.join(String(dir || ''), 'session.lock')
+      if (!existsSync(lock)) return false
+      return await new Promise((resolve) => {
+        try {
+          execFile('lsof', ['-t', '--', lock], { timeout: 3000 }, (error, stdout) => {
+            resolve(String(stdout || '').trim().length > 0)
+          })
+        } catch {
+          resolve(false)
+        }
+      })
+    }
+    return false
+  }
+
+  /** Drop one remote path from every machine's recent list and current workspace.
+   *
+   * Deleting a workspace must also forget its remote path, otherwise the TUI
+   * provider re-creates the mirror from `recentWorkspaces` on the next start.
+   *
+   * @param {string} remotePath - remote workspace path to forget.
+   * @returns {{recents: number, current: number}} how many fields changed.
+   */
+  const forgetRemotePath = (remotePath) => {
+    const target = String(remotePath || '').trim()
+    let recents = 0
+    let current = 0
+    if (!target) return { recents, current }
+    for (const machine of machines) {
+      if (Array.isArray(machine.recentWorkspaces)) {
+        const before = machine.recentWorkspaces.length
+        machine.recentWorkspaces = machine.recentWorkspaces.filter((entry) => String(entry) !== target)
+        recents += before - machine.recentWorkspaces.length
+      }
+      if (String(machine.workspace || '') === target) {
+        machine.workspace = ''
+        current += 1
+      }
+    }
+    if (recents > 0 || current > 0) saveMachines(machines, store.currentId, false)
+    return { recents, current }
+  }
   const sessionCwd = (sessionId) => {
     const sessions = sessionsSvc()
     if (sessionId) return lookupSessionCwd(sessionId, { sessions, dshHome: dshBase() })
@@ -3305,6 +3379,533 @@ export async function apply(ctx, config) {
     }
   }
 
+  /** Add/update one machine. Shared by POST /dsh-remote/machines and the
+   *  in-process API (`upsertMachine`). Returns the shape the route sends minus
+   *  `ok`; throws HOST_REQUIRED (httpStatus 400) for a missing host, which the
+   *  route maps back to its historical 400 response. */
+  const upsertMachineRecord = async (body) => {
+    let warning = ''
+    let warningDetail = ''
+    const host = String(body.host || '').trim()
+    if (!host) throw codedError('HOST_REQUIRED', 'host required', { httpStatus: 400 })
+    const id = body.id || machineId()
+    const i = machineIndex(id)
+    const prev = i >= 0 ? machines[i] : null
+    const credBackend = body.credentialBackend === 'plain' ? 'plain'
+      : (body.encryptPassword ? platformBackend() : (prev && prev.credentialBackend ? prev.credentialBackend : 'plain'))
+    const rec = {
+      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: '',
+      // An OMITTED `privateKeyPath` keeps the stored one; an explicit
+      // empty string clears it (that is what the form sends when the user
+      // empties the box). A partial update from an API/agent caller used
+      // to silently wipe the key path, leaving a machine that can only
+      // fail to authenticate — the same data-loss class as the passphrase.
+      privateKeyPath: body.privateKeyPath === undefined
+        ? String((prev && prev.privateKeyPath) || '')
+        : String(body.privateKeyPath || '').trim(),
+      // An EMPTY passphrase from the form means "unchanged", not
+      // "delete it": the value is never echoed back to the browser, so
+      // an edit that touched any other field used to silently wipe a
+      // saved private-key passphrase (and the next connect then failed
+      // with "no passphrase given" for a key that had been working).
+      passphrase: String(body.passphrase || (prev && prev.passphrase) || ''),
+      workspace: String(body.workspace || '').trim(),
+      hostKeyMode: body.hostKeyMode || '',
+      useAgent: !!body.useAgent,
+      keyboardInteractive: !!body.keyboardInteractive,
+      // Issue #51: the transport backend is per machine. `native` is
+      // the default, so an unknown value is not persisted as-is.
+      backend: body.backend === 'openssh' ? 'openssh' : 'native',
+      sshBinary: String(body.sshBinary || '').trim(),
+      // Issue #54: the per-machine `dsh web` launch command was only
+      // ever writable by the deploy flow or by hand-editing
+      // machines.json — the README told users to set it and the
+      // settings UI offered nowhere to type it. It is an ordinary
+      // machine field now; empty means "fall back to the global
+      // webAttachCommand".
+      webAttachCommand: body.webAttachCommand === undefined
+        ? String((prev && prev.webAttachCommand) || '')
+        : String(body.webAttachCommand || '').trim(),
+      // Group labels (host organisation). Merge-only: a request that
+      // omits them keeps the stored values instead of wiping them.
+      ...normalizeMachineGroup({
+        environment: body.environment === undefined ? (prev && prev.environment) : body.environment,
+        location: body.location === undefined ? (prev && prev.location) : body.location,
+        description: body.description === undefined ? (prev && prev.description) : body.description,
+        tags: body.tags === undefined ? (prev && prev.tags) : body.tags,
+      }),
+      // A jump host the form did not mention is KEPT (omitted ≠
+      // removed), and a jump PASSWORD the form did not re-supply is
+      // kept too: the settings page never receives it back, so an edit
+      // used to strip the bastion credential and the machine could
+      // only fail at connect time.
+      proxy: body.proxy === undefined
+        ? (prev && prev.proxy && prev.proxy.host ? prev.proxy : undefined)
+        : (body.proxy && body.proxy.host ? {
+            host: String(body.proxy.host),
+            port: Number(body.proxy.port) || 22,
+            username: String(body.proxy.username || '').trim(),
+            password: String(body.proxy.password || (prev && prev.proxy && prev.proxy.password) || ''),
+            privateKeyPath: String(body.proxy.privateKeyPath || '').trim(),
+          } : undefined),
+      credentialBackend: credBackend,
+      recentWorkspaces: prev && prev.recentWorkspaces ? prev.recentWorkspaces : [],
+      lastConnectedAt: prev && prev.lastConnectedAt ? prev.lastConnectedAt : null,
+      latencyMs: prev && prev.latencyMs ? prev.latencyMs : null,
+    }
+    if (body.password) {
+      // Issue #30: `saveSecret()` is best-effort — the old code threw
+      // its result away and kept `password: ''`, so on Windows (DPAPI
+      // missing the System.Security assembly) the machine was saved
+      // WITHOUT any credential and every later connect failed with no
+      // visible reason. Now a failed OS-store write falls back to
+      // plaintext and is reported to the UI.
+      const persisted = await persistPassword({
+        backend: credBackend,
+        machineId: id,
+        password: body.password,
+        secretsDir: secretsDir(),
+        onStoreFailure: config.credentialFallback === 'plain' ? 'plain' : 'refuse',
+      })
+      rec.credentialBackend = persisted.credentialBackend
+      rec.password = persisted.password
+      // Record WHERE the secret ended up, so the settings page can say
+      // "已保存" for a keychain machine too (its record carries an
+      // empty `password` by design).
+      rec.secretStored = persisted.stored === 'secret'
+      if (persisted.warning) {
+        warning = persisted.warning
+        warningDetail = persisted.error
+      }
+    } else if (prev) {
+      // No password typed: keep whatever the machine already had —
+      // the plaintext copy AND the keychain flag. Turning the
+      // "加密保存密码" checkbox OFF is handled next: it must actually
+      // MOVE the secret, or the checkbox is a lie.
+      rec.password = prev.password || ''
+      rec.secretStored = prev.secretStored
+      const prevKeychain = prev.credentialBackend && prev.credentialBackend !== 'plain'
+      if (credBackend === 'plain' && prevKeychain) {
+        try {
+          const existing = await machinePassword(prev)
+          if (existing) {
+            rec.password = existing
+            rec.secretStored = false
+            rec.credentialBackend = 'plain'
+            await deleteSecret(id, secretsDir()).catch(() => {})
+          }
+        } catch { /* keep the keychain copy; the next connect still works */ }
+      }
+    }
+    if (i >= 0) machines[i] = rec; else machines.push(rec)
+    // Issue #13: saving a machine must NOT make it the active
+    // remote context. `currentId` stays untouched on add/update —
+    // only an explicit "设为当前" (or rw_connect) activates one.
+    // keepCurrentKey:false leaves the stored `currentId` byte-for-byte
+    // alone, so a fresh registry stays "no choice yet" (not an
+    // explicit none) and a previously-cleared registry stays cleared.
+    saveMachines(machines, store.currentId, false)
+    // Issue #67: an EDITED connection identity (host/user/port) must
+    // carry the machine's existing workspaces over — without this the
+    // mirrors stayed bound to the old address and the user had to
+    // create (and re-sync) a brand-new workspace for the new IP.
+    let reboundMirrors = 0
+    if (i >= 0 && prev) {
+      try { reboundMirrors = rebindMirrors(prev, rec) } catch { /* best effort */ }
+    }
+    // Issue #50: host/user/port/key have ONE home — ~/.ssh/config.
+    // Saving a literal machine upserts a marker-tagged Host block,
+    // so the file and the registry can never drift; the record's
+    // copy remains only as a fallback for a missing/renamed block.
+    // A Host block the USER wrote for the same name is never
+    // touched — the conflict is reported instead. Failures here are
+    // best-effort: the registry copy is already saved.
+    let sshConfigWarning = ''
+    if (!rec.useSshConfig) {
+      try {
+        const raw = readRawSshConfig(sshConfigPath())
+        let next = upsertManagedHostBlock(raw, {
+          alias: rec.host,
+          hostName: rec.host,
+          user: rec.username,
+          port: rec.port,
+          identityFile: rec.privateKeyPath,
+        })
+        // A RENAMED machine leaves the old managed block behind, and
+        // that block is the plugin's own artifact of the edit —
+        // retire it. (Deleting a machine removes nothing: the Host
+        // block is the user's ssh access, not plugin state.)
+        if (prev && prev.host && prev.host !== rec.host && !prev.useSshConfig) {
+          const rm = removeManagedHostBlock(next.text, prev.host)
+          next = { status: rm.status === 'removed' && next.status === 'unchanged' ? 'updated' : next.status, text: rm.text }
+        }
+        if (next.status === 'conflict') {
+          sshConfigWarning = `~/.ssh/config already names "${rec.host}" in a Host block that is not managed by dsh-remote — it was left untouched, and it now wins over the saved copy.`
+        } else if (next.status === 'appended' || next.status === 'updated') {
+          writeSshConfig(next.text, sshConfigPath())
+          sshConfigCache = { text: '', at: 0 }
+        }
+      } catch (sshErr) {
+        sshConfigWarning = `could not update ~/.ssh/config (${String((sshErr && sshErr.message) || sshErr)}); the registry copy was saved.`
+      }
+    }
+    return {
+      machine: sanitizeMachine(rec),
+      machines: machinesForClient(),
+      currentId: store.currentId,
+      ...(reboundMirrors ? { reboundMirrors } : {}),
+      ...(warning ? { warning, warningDetail } : {}),
+      ...(sshConfigWarning ? { sshConfigWarning } : {}),
+    }
+  }
+
+  /** Delete one machine (never auto-promotes a sibling). Shared by the
+   *  delete route and the in-process API; throws MACHINE_NOT_FOUND.
+   *  @param {string} id - machine id. */
+  const removeMachineRecord = async (id) => {
+    const i = machineIndex(String(id || ''))
+    if (i < 0) throw codedError('MACHINE_NOT_FOUND', 'machine not found', { httpStatus: 404 })
+    const m = machines[i]
+    if (m.credentialBackend && m.credentialBackend !== 'plain') {
+      await deleteSecret(m.id, secretsDir()).catch(() => {})
+    }
+    machines.splice(i, 1)
+    const wasCurrent = store.currentId === m.id
+    if (wasCurrent) {
+      // Issue #13: deleting the current machine leaves NO active
+      // remote context (never auto-promote a sibling — that would
+      // make an unrelated machine leak into the session again).
+      store.currentId = null
+      saveMachines(machines, null)
+      await clearActiveMachine()
+    } else {
+      saveMachines(machines, store.currentId)
+    }
+    return { machines: machinesForClient(), currentId: store.currentId }
+  }
+
+  /** Unpersisted connectivity probe: dial once with the credentials a REAL
+   *  connect would use (form values override, blanks fall back to the stored
+   *  record), report latency/platform/shell. Shared by POST
+   *  /dsh-remote/test-connect and the in-process API; throws on failure. */
+  const probeMachineRecord = async (body) => {
+    // ── The probe must dial with the credentials a REAL connect would use.
+    //
+    // Stored secrets never travel back to the browser (see
+    // sanitizeMachine), so "编辑一台已经连接成功的机器 → 点测试连接" posted an
+    // EMPTY password while the machine itself connected fine through the
+    // pool's keychain/plaintext resolver. Every such probe died with
+    // `no credentials: set a password, a privateKeyPath, or enable
+    // useAgent to connect` — the error said "you configured nothing" about
+    // a machine that was visibly working.
+    //
+    // So: resolve the saved record (by id when the form is editing one,
+    // else by identity) and merge — form values override, blanks fall back
+    // to the stored record. The resolved password is then ALSO exposed as a
+    // lazy resolver so an OS-keychain machine behaves exactly like a real
+    // connect (read on demand, never logged).
+    const savedRec = (() => {
+      const byId = body.id ? machines[machineIndex(String(body.id))] : null
+      if (byId) return byId
+      // No id (a fresh form that happens to match a saved machine): match on
+      // the identity the form is about to dial.
+      const hit = machineRecordFor({
+        host: String(body.host || ''),
+        port: Number(body.port) || 22,
+        username: String(body.username || ''),
+      })
+      return hit || null
+    })()
+    const savedPassword = savedRec ? await machinePassword(savedRec) : ''
+    const cred = resolveProbeCredentials(body, savedRec, savedPassword)
+    // 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 probeBackend = String(cred.backend || config.backend || 'native')
+    const probeIsOpenssh = isSystemOpenSshBackend({ backend: probeBackend })
+    const aliasTarget = body.useSshConfig
+      ? resolveMachineSshConfig({
+          host: String(body.host || ''),
+          port: Number(body.port) || 22,
+          username: String(body.username || ''),
+          privateKeyPath: String(cred.privateKeyPath || ''),
+          proxy: cred.proxy,
+          useSshConfig: true,
+        }, { text: sshConfigText() })
+      : null
+    // Issue #50: a LITERAL host named by a Host block resolves through
+    // the file as well — the probe must dial what a real connect would.
+    const literalTarget = !body.useSshConfig
+      ? resolveLiteralSshConfig({ host: String(body.host || '') }, { text: sshConfigText() })
+      : null
+    const probeTarget = aliasTarget || literalTarget
+    // Issue #51: on the system-OpenSSH backend an alias is handed to `ssh`
+    // VERBATIM (see connectTargetFor) — resolving it here would stop the
+    // `Host` block from matching, so the ~/.ssh/config settings the probe
+    // is supposed to validate would be silently skipped.
+    const probe = createPool({
+      ...config,
+      backend: probeBackend,
+      host: probeTarget && !probeIsOpenssh ? probeTarget.host : String(body.host || config.host),
+      port: (probeTarget && !probeIsOpenssh && probeTarget.port) ? probeTarget.port : (Number(body.port) || config.port),
+      username: (probeTarget && !probeIsOpenssh && probeTarget.username) ? probeTarget.username : String(body.username || config.username),
+      password: cred.password,
+      privateKeyPath: (probeTarget && !probeIsOpenssh && probeTarget.privateKeyPath) ? probeTarget.privateKeyPath : String(cred.privateKeyPath || config.privateKeyPath),
+      passphrase: cred.passphrase,
+      // Auth METHOD flags come from the merge too: a machine that
+      // authenticates through an agent or keyboard-interactive used to be
+      // probed with `useAgent: false`, i.e. with no auth method at all.
+      useAgent: cred.useAgent,
+      agentSocket: (probeTarget && !probeIsOpenssh && probeTarget.agentSocket) || '',
+      identitiesOnly: !!(probeTarget && !probeIsOpenssh && probeTarget.identitiesOnly),
+      keyboardInteractive: cred.keyboardInteractive,
+      ...(cred.hostKeyMode ? { hostKeyMode: cred.hostKeyMode } : {}),
+      ...(cred.sshBinary ? { sshBinary: cred.sshBinary } : {}),
+      proxy: (probeTarget && !probeIsOpenssh && probeTarget.proxy) ? probeTarget.proxy : cred.proxy,
+      connectTimeoutMs: Math.min(Math.max(Number(body.connectTimeoutMs) || config.connectTimeoutMs, 2000), 30000),
+      commandTimeoutMs: 10000,
+    }, { knownHostsFile })
+    // Same lazy resolution the active pool uses: if the merged password was
+    // empty because the secret lives in the OS keychain, the pool asks again
+    // at dial time instead of failing with "no credentials".
+    probe.passwordResolver = async () => machinePassword(savedRec || {})
+    const started = Date.now()
+    await probe.connect()
+    await probe.exec('true', { timeoutMs: 10000 })
+    probe.close()
+    const latencyMs = Date.now() - started
+    // 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 {
+      ok: true,
+      host: probe.config.host,
+      user: probe.config.username,
+      latencyMs,
+      lastConnectedAt: new Date().toISOString(),
+      platform: probe.platform,
+      shell: probe.shellMode,
+      gitBash: probe.gitBashPath || '',
+      // Tell the UI whether the probe leaned on the SAVED credential: with
+      // an empty password box, "测试成功" otherwise looks impossible.
+      usedSavedCredential: cred.usedSavedCredential,
+      // 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,
+    }
+  }
+  // ── in-process host API (ctx.dshRemote) building blocks ───────────────────
+  // lib/host-api.js owns the contract shaping (pure data, error codes,
+  // subscribe); the functions below are the only bridge to this closure's
+  // state. ONE implementation is the point: a second reader of machines.json
+  // would see a stale snapshot, a second SSH pool would double every
+  // connection, and two writers of saveMachines() race its whole-file rewrite.
+  /** Log through the optional harness logger; never lets logging fail a call. */
+  const hostLog = (level, message) => {
+    try {
+      const logger = ctx && typeof ctx.get === 'function' ? ctx.get('logger') : undefined
+      if (logger && typeof logger[level] === 'function') logger[level](message)
+    } catch { /* logging is best-effort */ }
+  }
+
+  /** One coded error for the in-process API. Host-side callers get a stable
+   *  `.code` (contract vocabulary) plus `httpStatus` where the HTTP route has
+   *  a historical status to preserve. */
+  const codedError = (code, message, extra = {}) => {
+    const e = new Error(message)
+    e.code = code
+    if (extra && typeof extra === 'object') Object.assign(e, extra)
+    return e
+  }
+
+  /** Resolve a machine for the API: by id when given, else the ACTIVE machine
+   *  (explicit current > ephemeral > config default, exactly like status()).
+   *  Returns the RESOLVED connect identity — ssh-config aliases expanded, and
+   *  folded back to the alias for the system-OpenSSH backend (which dials the
+   *  alias itself), i.e. what applyActiveMachine writes into the shared config. */
+  const resolveMachineForApi = (machineId) => {
+    const id = String(machineId || '').trim()
+    if (id) {
+      const i = machineIndex(id)
+      if (i < 0) throw codedError('MACHINE_NOT_FOUND', `machine not found: ${id}`)
+      const rec = machines[i]
+      const eff = withSshConfig(rec)
+      const t = connectTargetFor(eff)
+      return {
+        record: rec,
+        machineId: rec.id,
+        name: String(rec.name || rec.host || ''),
+        host: String(t.aliasNative ? t.host : (eff.host || '')),
+        port: t.aliasNative ? 22 : (Number(eff.port) || 22),
+        username: t.aliasNative ? '' : String(eff.username || ''),
+        alias: aliasOf(eff),
+      }
+    }
+    const rec = store.currentId && machineIndex(store.currentId) >= 0 ? machines[machineIndex(store.currentId)] : null
+    const m = activeMachine()
+    if (!m || !m.host) {
+      throw codedError('NO_ACTIVE_MACHINE', '当前没有活动远程机：请先在「远程工作区」设置里选择或连接一台机器。（保存的机器只是备用连接，不会自动成为当前机器。）')
+    }
+    const t = connectTargetFor(m)
+    return {
+      record: rec,
+      machineId: rec ? rec.id : '',
+      name: String((rec && rec.name) || m.name || m.host || ''),
+      host: String(t.aliasNative ? t.host : (m.host || '')),
+      port: t.aliasNative ? 22 : (Number(m.port) || 22),
+      username: t.aliasNative ? '' : String(m.username || ''),
+      alias: aliasOf(m),
+    }
+  }
+
+  /** Binding for the API's listDir. Addressing priority (contract):
+   *  machineId (that machine's own pool, no side effects) > the active machine
+   *  (the same fallback the /ls route gets from resolveRequestBinding). */
+  const listDirBindingForApi = async (opts = {}) => {
+    const id = String((opts && opts.machineId) || '').trim()
+    if (id) {
+      const m = resolveMachineForApi(id)
+      // The per-machine pool keeps browsing off the shared active pool: a
+      // directory listing must never switch the user's current machine.
+      const targetPool = poolForMachine({ host: m.host, port: m.port, username: m.username, alias: m.alias })
+      const tgt = (targetPool && targetPool.config) || {}
+      return {
+        pool: targetPool,
+        ws: '',
+        bound: false,
+        machine: {
+          id: m.machineId,
+          name: m.name,
+          host: String(tgt.host || m.host),
+          port: Number(tgt.port) || m.port,
+          username: String(tgt.username != null ? tgt.username : m.username),
+        },
+      }
+    }
+    // No hint: the /ls route's fallback. resolveRequestBinding throws a 409 with
+    // the actionable Chinese message when no machine is active; host-api maps
+    // that to NO_ACTIVE_MACHINE.
+    const b = await resolveRequestBinding({ url: '/' }, {})
+    let name = ''
+    try {
+      const am = activeMachine()
+      name = String((am && (am.name || am.host)) || b.host || '')
+    } catch { /* display only */ }
+    const tgt = (b.pool && b.pool.config) || {}
+    return {
+      pool: b.pool,
+      ws: b.ws,
+      bound: !!b.bound,
+      machine: {
+        id: store.currentId || '',
+        name,
+        host: String(tgt.host || b.host || ''),
+        port: Number(tgt.port) || Number(b.port) || 22,
+        username: String(tgt.username != null ? tgt.username : (b.username || '')),
+      },
+    }
+  }
+
+  /** Every local mirror + the registry machine its meta resolves to. Pure
+   *  filesystem read (mirrorRegistry), so it never dials. */
+  const listRemoteProjectsForApi = () => mirrorRegistry().map((p) => {
+    const rec = machineRecordFor({ host: p.host, port: p.port, username: p.username, alias: p.alias })
+    return { ...p, machineId: rec && rec.id ? String(rec.id) : null }
+  })
+
+  /** SSH `stat` validation used by pickRemoteWorkspace. With a machineId it
+   *  runs on that machine's OWN pool (validation must not switch the active
+   *  machine); without one it behaves like the /mirror route (active pool). */
+  const checkRemoteDirForApi = async (remotePath, machineId) => {
+    const id = String(machineId || '').trim()
+    if (id) {
+      const m = resolveMachineForApi(id)
+      return isRemoteDir(remotePath, poolForMachine({ host: m.host, port: m.port, username: m.username, alias: m.alias }))
+    }
+    if (!String(config.host || '').trim()) {
+      const m = activeMachine()
+      if (m && m.host) {
+        try { await applyActiveMachine() } catch { /* reported by the probe below */ }
+      }
+    }
+    if (!String(config.host || '').trim()) {
+      throw codedError('NO_ACTIVE_MACHINE', '当前没有活动远程机：请先在「远程工作区」设置里选择或连接一台机器。（保存的机器只是备用连接，不会自动成为当前机器。）')
+    }
+    return isRemoteDir(remotePath)
+  }
+
+  /** Persist "this machine is current" for the API (null = explicit none). */
+  const setCurrentForApi = async (id) => {
+    const clean = id == null ? '' : String(id).trim()
+    if (!clean) {
+      await setCurrent('')
+      return
+    }
+    if (machineIndex(clean) < 0) throw codedError('MACHINE_NOT_FOUND', `machine not found: ${clean}`)
+    if (!(await setCurrent(clean))) throw codedError('MACHINE_NOT_FOUND', `machine not found: ${clean}`)
+  }
+
+  /** Connect (activate) a machine and probe a real SSH connection.
+   *  `persist:false` keeps the registry's currentId untouched (rw_connect
+   *  save:false semantics): the target is applied as an EPHEMERAL machine. */
+  const connectMachineForApi = async (opts = {}) => {
+    const id = String((opts && opts.machineId) || '').trim()
+    const persist = !(opts && opts.persist === false)
+    let rec = null
+    if (id) {
+      const i = machineIndex(id)
+      if (i < 0) throw codedError('MACHINE_NOT_FOUND', `machine not found: ${id}`)
+      rec = machines[i]
+    } else if (store.currentId && machineIndex(store.currentId) >= 0) {
+      rec = machines[machineIndex(store.currentId)]
+    }
+    if (!rec) {
+      const m = activeMachine()
+      if (!m || !m.host) {
+        throw codedError('NO_ACTIVE_MACHINE', '当前没有活动远程机：请先在「远程工作区」设置里选择或连接一台机器。（保存的机器只是备用连接，不会自动成为当前机器。）')
+      }
+    }
+    if (persist) {
+      ephemeral = null
+      if (rec) await setCurrent(rec.id)
+      else await applyActiveMachine()
+    } else {
+      ephemeral = rec ? { ...rec } : { ...activeMachine() }
+      await applyActiveMachine()
+    }
+    // "Connect" means dial NOW: drop a cached (possibly half-open) client so the
+    // probe below really reconnects — the same reasoning as the /connect route.
+    pool.invalidate()
+    const connectHost = config.host
+    const connectPort = Number(config.port) || 22
+    try {
+      await pool.exec('echo ok', { timeoutMs: Math.min(config.commandTimeoutMs || 20000, 8000) })
+    } catch (err) {
+      if (err && typeof err === 'object') {
+        err.host = connectHost
+        err.port = connectPort
+      }
+      audit('connect', `connect ${config.username}@${connectHost}:${connectPort}`, (err && typeof err.code === 'number') ? err.code : -1)
+      throw err
+    }
+    audit('connect', `connect ${config.username}@${connectHost}:${connectPort}`, 0)
+    return status()
+  }
+
+
   // ── route helpers ─────────────────────────────────────────────────────────
   const routes = [
     {
@@ -3668,190 +4269,12 @@ export async function apply(ctx, config) {
           try {
             const body = JSON.parse((await readBody(req)) || '{}')
             const action = body.action || 'add'
-            let warning = ''
-            let warningDetail = ''
             if (action === 'add' || action === 'update') {
-              const host = String(body.host || '').trim()
-              if (!host) return sendJson(res, 400, { ok: false, error: 'host required' })
-              const id = body.id || machineId()
-              const i = machineIndex(id)
-              const prev = i >= 0 ? machines[i] : null
-              const credBackend = body.credentialBackend === 'plain' ? 'plain'
-                : (body.encryptPassword ? platformBackend() : (prev && prev.credentialBackend ? prev.credentialBackend : 'plain'))
-              const rec = {
-                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: '',
-                // An OMITTED `privateKeyPath` keeps the stored one; an explicit
-                // empty string clears it (that is what the form sends when the user
-                // empties the box). A partial update from an API/agent caller used
-                // to silently wipe the key path, leaving a machine that can only
-                // fail to authenticate — the same data-loss class as the passphrase.
-                privateKeyPath: body.privateKeyPath === undefined
-                  ? String((prev && prev.privateKeyPath) || '')
-                  : String(body.privateKeyPath || '').trim(),
-                // An EMPTY passphrase from the form means "unchanged", not
-                // "delete it": the value is never echoed back to the browser, so
-                // an edit that touched any other field used to silently wipe a
-                // saved private-key passphrase (and the next connect then failed
-                // with "no passphrase given" for a key that had been working).
-                passphrase: String(body.passphrase || (prev && prev.passphrase) || ''),
-                workspace: String(body.workspace || '').trim(),
-                hostKeyMode: body.hostKeyMode || '',
-                useAgent: !!body.useAgent,
-                keyboardInteractive: !!body.keyboardInteractive,
-                // Issue #51: the transport backend is per machine. `native` is
-                // the default, so an unknown value is not persisted as-is.
-                backend: body.backend === 'openssh' ? 'openssh' : 'native',
-                sshBinary: String(body.sshBinary || '').trim(),
-                // Issue #54: the per-machine `dsh web` launch command was only
-                // ever writable by the deploy flow or by hand-editing
-                // machines.json — the README told users to set it and the
-                // settings UI offered nowhere to type it. It is an ordinary
-                // machine field now; empty means "fall back to the global
-                // webAttachCommand".
-                webAttachCommand: body.webAttachCommand === undefined
-                  ? String((prev && prev.webAttachCommand) || '')
-                  : String(body.webAttachCommand || '').trim(),
-                // Group labels (host organisation). Merge-only: a request that
-                // omits them keeps the stored values instead of wiping them.
-                ...normalizeMachineGroup({
-                  environment: body.environment === undefined ? (prev && prev.environment) : body.environment,
-                  location: body.location === undefined ? (prev && prev.location) : body.location,
-                  description: body.description === undefined ? (prev && prev.description) : body.description,
-                  tags: body.tags === undefined ? (prev && prev.tags) : body.tags,
-                }),
-                // A jump host the form did not mention is KEPT (omitted ≠
-                // removed), and a jump PASSWORD the form did not re-supply is
-                // kept too: the settings page never receives it back, so an edit
-                // used to strip the bastion credential and the machine could
-                // only fail at connect time.
-                proxy: body.proxy === undefined
-                  ? (prev && prev.proxy && prev.proxy.host ? prev.proxy : undefined)
-                  : (body.proxy && body.proxy.host ? {
-                      host: String(body.proxy.host),
-                      port: Number(body.proxy.port) || 22,
-                      username: String(body.proxy.username || '').trim(),
-                      password: String(body.proxy.password || (prev && prev.proxy && prev.proxy.password) || ''),
-                      privateKeyPath: String(body.proxy.privateKeyPath || '').trim(),
-                    } : undefined),
-                credentialBackend: credBackend,
-                recentWorkspaces: prev && prev.recentWorkspaces ? prev.recentWorkspaces : [],
-                lastConnectedAt: prev && prev.lastConnectedAt ? prev.lastConnectedAt : null,
-                latencyMs: prev && prev.latencyMs ? prev.latencyMs : null,
-              }
-              if (body.password) {
-                // Issue #30: `saveSecret()` is best-effort — the old code threw
-                // its result away and kept `password: ''`, so on Windows (DPAPI
-                // missing the System.Security assembly) the machine was saved
-                // WITHOUT any credential and every later connect failed with no
-                // visible reason. Now a failed OS-store write falls back to
-                // plaintext and is reported to the UI.
-                const persisted = await persistPassword({
-                  backend: credBackend,
-                  machineId: id,
-                  password: body.password,
-                  secretsDir: secretsDir(),
-                  onStoreFailure: config.credentialFallback === 'plain' ? 'plain' : 'refuse',
-                })
-                rec.credentialBackend = persisted.credentialBackend
-                rec.password = persisted.password
-                // Record WHERE the secret ended up, so the settings page can say
-                // "已保存" for a keychain machine too (its record carries an
-                // empty `password` by design).
-                rec.secretStored = persisted.stored === 'secret'
-                if (persisted.warning) {
-                  warning = persisted.warning
-                  warningDetail = persisted.error
-                }
-              } else if (prev) {
-                // No password typed: keep whatever the machine already had —
-                // the plaintext copy AND the keychain flag. Turning the
-                // "加密保存密码" checkbox OFF is handled next: it must actually
-                // MOVE the secret, or the checkbox is a lie.
-                rec.password = prev.password || ''
-                rec.secretStored = prev.secretStored
-                const prevKeychain = prev.credentialBackend && prev.credentialBackend !== 'plain'
-                if (credBackend === 'plain' && prevKeychain) {
-                  try {
-                    const existing = await machinePassword(prev)
-                    if (existing) {
-                      rec.password = existing
-                      rec.secretStored = false
-                      rec.credentialBackend = 'plain'
-                      await deleteSecret(id, secretsDir()).catch(() => {})
-                    }
-                  } catch { /* keep the keychain copy; the next connect still works */ }
-                }
-              }
-              if (i >= 0) machines[i] = rec; else machines.push(rec)
-              // Issue #13: saving a machine must NOT make it the active
-              // remote context. `currentId` stays untouched on add/update —
-              // only an explicit "设为当前" (or rw_connect) activates one.
-              // keepCurrentKey:false leaves the stored `currentId` byte-for-byte
-              // alone, so a fresh registry stays "no choice yet" (not an
-              // explicit none) and a previously-cleared registry stays cleared.
-              saveMachines(machines, store.currentId, false)
-              // Issue #67: an EDITED connection identity (host/user/port) must
-              // carry the machine's existing workspaces over — without this the
-              // mirrors stayed bound to the old address and the user had to
-              // create (and re-sync) a brand-new workspace for the new IP.
-              let reboundMirrors = 0
-              if (i >= 0 && prev) {
-                try { reboundMirrors = rebindMirrors(prev, rec) } catch { /* best effort */ }
-              }
-              // Issue #50: host/user/port/key have ONE home — ~/.ssh/config.
-              // Saving a literal machine upserts a marker-tagged Host block,
-              // so the file and the registry can never drift; the record's
-              // copy remains only as a fallback for a missing/renamed block.
-              // A Host block the USER wrote for the same name is never
-              // touched — the conflict is reported instead. Failures here are
-              // best-effort: the registry copy is already saved.
-              let sshConfigWarning = ''
-              if (!rec.useSshConfig) {
-                try {
-                  const raw = readRawSshConfig(sshConfigPath())
-                  let next = upsertManagedHostBlock(raw, {
-                    alias: rec.host,
-                    hostName: rec.host,
-                    user: rec.username,
-                    port: rec.port,
-                    identityFile: rec.privateKeyPath,
-                  })
-                  // A RENAMED machine leaves the old managed block behind, and
-                  // that block is the plugin's own artifact of the edit —
-                  // retire it. (Deleting a machine removes nothing: the Host
-                  // block is the user's ssh access, not plugin state.)
-                  if (prev && prev.host && prev.host !== rec.host && !prev.useSshConfig) {
-                    const rm = removeManagedHostBlock(next.text, prev.host)
-                    next = { status: rm.status === 'removed' && next.status === 'unchanged' ? 'updated' : next.status, text: rm.text }
-                  }
-                  if (next.status === 'conflict') {
-                    sshConfigWarning = `~/.ssh/config already names "${rec.host}" in a Host block that is not managed by dsh-remote — it was left untouched, and it now wins over the saved copy.`
-                  } else if (next.status === 'appended' || next.status === 'updated') {
-                    writeSshConfig(next.text, sshConfigPath())
-                    sshConfigCache = { text: '', at: 0 }
-                  }
-                } catch (sshErr) {
-                  sshConfigWarning = `could not update ~/.ssh/config (${String((sshErr && sshErr.message) || sshErr)}); the registry copy was saved.`
-                }
+              try {
+                return sendJson(res, 200, { ok: true, ...(await upsertMachineRecord(body)) })
+              } catch (err) {
+                return sendJson(res, (err && err.httpStatus) || 500, { ok: false, error: String((err && err.message) || err) })
               }
-              return sendJson(res, 200, {
-                ok: true,
-                machine: sanitizeMachine(rec),
-                machines: machinesForClient(),
-                currentId: store.currentId,
-                ...(reboundMirrors ? { reboundMirrors } : {}),
-                ...(warning ? { warning, warningDetail } : {}),
-                ...(sshConfigWarning ? { sshConfigWarning } : {}),
-              })
             }
             // Issue #73: one click on a host listed from ~/.ssh/config. The settings
             // page no longer asks the user to understand "alias" vs "copy": it lists
@@ -3910,25 +4333,11 @@ export async function apply(ctx, config) {
               })
             }
             if (action === 'delete') {
-              const i = machineIndex(String(body.id || ''))
-              if (i < 0) return sendJson(res, 404, { ok: false, error: 'machine not found' })
-              const m = machines[i]
-              if (m.credentialBackend && m.credentialBackend !== 'plain') {
-                await deleteSecret(m.id, secretsDir()).catch(() => {})
-              }
-              machines.splice(i, 1)
-              const wasCurrent = store.currentId === m.id
-              if (wasCurrent) {
-                // Issue #13: deleting the current machine leaves NO active
-                // remote context (never auto-promote a sibling — that would
-                // make an unrelated machine leak into the session again).
-                store.currentId = null
-                saveMachines(machines, null)
-                await clearActiveMachine()
-              } else {
-                saveMachines(machines, store.currentId)
+              try {
+                return sendJson(res, 200, { ok: true, ...(await removeMachineRecord(String(body.id || ''))) })
+              } catch (err) {
+                return sendJson(res, (err && err.httpStatus) || 500, { ok: false, error: String((err && err.message) || err) })
               }
-              return sendJson(res, 200, { ok: true, machines: machinesForClient(), currentId: store.currentId })
             }
             return sendJson(res, 400, { ok: false, error: 'unknown action' })
           } catch (err) {
@@ -3951,114 +4360,7 @@ export async function apply(ctx, config) {
         let body = {}
         try {
           body = parseJsonObject(await readBody(req))
-          // ── The probe must dial with the credentials a REAL connect would use.
-          //
-          // Stored secrets never travel back to the browser (see
-          // sanitizeMachine), so "编辑一台已经连接成功的机器 → 点测试连接" posted an
-          // EMPTY password while the machine itself connected fine through the
-          // pool's keychain/plaintext resolver. Every such probe died with
-          // `no credentials: set a password, a privateKeyPath, or enable
-          // useAgent to connect` — the error said "you configured nothing" about
-          // a machine that was visibly working.
-          //
-          // So: resolve the saved record (by id when the form is editing one,
-          // else by identity) and merge — form values override, blanks fall back
-          // to the stored record. The resolved password is then ALSO exposed as a
-          // lazy resolver so an OS-keychain machine behaves exactly like a real
-          // connect (read on demand, never logged).
-          const savedRec = (() => {
-            const byId = body.id ? machines[machineIndex(String(body.id))] : null
-            if (byId) return byId
-            // No id (a fresh form that happens to match a saved machine): match on
-            // the identity the form is about to dial.
-            const hit = machineRecordFor({
-              host: String(body.host || ''),
-              port: Number(body.port) || 22,
-              username: String(body.username || ''),
-            })
-            return hit || null
-          })()
-          const savedPassword = savedRec ? await machinePassword(savedRec) : ''
-          const cred = resolveProbeCredentials(body, savedRec, savedPassword)
-          // 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 probeBackend = String(cred.backend || config.backend || 'native')
-          const probeIsOpenssh = isSystemOpenSshBackend({ backend: probeBackend })
-          const aliasTarget = body.useSshConfig
-            ? resolveMachineSshConfig({
-                host: String(body.host || ''),
-                port: Number(body.port) || 22,
-                username: String(body.username || ''),
-                privateKeyPath: String(cred.privateKeyPath || ''),
-                proxy: cred.proxy,
-                useSshConfig: true,
-              }, { text: sshConfigText() })
-            : null
-          // Issue #50: a LITERAL host named by a Host block resolves through
-          // the file as well — the probe must dial what a real connect would.
-          const literalTarget = !body.useSshConfig
-            ? resolveLiteralSshConfig({ host: String(body.host || '') }, { text: sshConfigText() })
-            : null
-          const probeTarget = aliasTarget || literalTarget
-          // Issue #51: on the system-OpenSSH backend an alias is handed to `ssh`
-          // VERBATIM (see connectTargetFor) — resolving it here would stop the
-          // `Host` block from matching, so the ~/.ssh/config settings the probe
-          // is supposed to validate would be silently skipped.
-          const probe = createPool({
-            ...config,
-            backend: probeBackend,
-            host: probeTarget && !probeIsOpenssh ? probeTarget.host : String(body.host || config.host),
-            port: (probeTarget && !probeIsOpenssh && probeTarget.port) ? probeTarget.port : (Number(body.port) || config.port),
-            username: (probeTarget && !probeIsOpenssh && probeTarget.username) ? probeTarget.username : String(body.username || config.username),
-            password: cred.password,
-            privateKeyPath: (probeTarget && !probeIsOpenssh && probeTarget.privateKeyPath) ? probeTarget.privateKeyPath : String(cred.privateKeyPath || config.privateKeyPath),
-            passphrase: cred.passphrase,
-            // Auth METHOD flags come from the merge too: a machine that
-            // authenticates through an agent or keyboard-interactive used to be
-            // probed with `useAgent: false`, i.e. with no auth method at all.
-            useAgent: cred.useAgent,
-            agentSocket: (probeTarget && !probeIsOpenssh && probeTarget.agentSocket) || '',
-            identitiesOnly: !!(probeTarget && !probeIsOpenssh && probeTarget.identitiesOnly),
-            keyboardInteractive: cred.keyboardInteractive,
-            ...(cred.hostKeyMode ? { hostKeyMode: cred.hostKeyMode } : {}),
-            ...(cred.sshBinary ? { sshBinary: cred.sshBinary } : {}),
-            proxy: (probeTarget && !probeIsOpenssh && probeTarget.proxy) ? probeTarget.proxy : cred.proxy,
-            connectTimeoutMs: Math.min(Math.max(Number(body.connectTimeoutMs) || config.connectTimeoutMs, 2000), 30000),
-            commandTimeoutMs: 10000,
-          }, { knownHostsFile })
-          // Same lazy resolution the active pool uses: if the merged password was
-          // empty because the secret lives in the OS keychain, the pool asks again
-          // at dial time instead of failing with "no credentials".
-          probe.passwordResolver = async () => machinePassword(savedRec || {})
-          const started = Date.now()
-          await probe.connect()
-          await probe.exec('true', { timeoutMs: 10000 })
-          probe.close()
-          const latencyMs = Date.now() - started
-          // 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 || '',
-            // Tell the UI whether the probe leaned on the SAVED credential: with
-            // an empty password box, "测试成功" otherwise looks impossible.
-            usedSavedCredential: cred.usedSavedCredential,
-            // 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,
-          })
+          return sendJson(res, 200, await probeMachineRecord(body))
         } catch (err) {
           return sendJson(res, 200, { ok: false, error: friendlyMessage(err, { host: body.host, port: body.port }) })
         }
@@ -4548,4 +4850,74 @@ export async function apply(ctx, config) {
     if (typeof updateTimer.unref === 'function') updateTimer.unref()
     ctx.effect(() => () => clearInterval(updateTimer), 'dsh-remote.update-timer')
   }
-}
+
+  // ── in-process API for other plugins (TUI) ────────────────────────────────
+  // Same closure state the HTTP routes use. A second implementation would hold
+  // a stale `machines` snapshot, open a second SSH connection per host, and
+  // race saveMachines()'s whole-file rewrite against this one. `lib/host-api.js`
+  // only shapes these functions into pure data + coded errors.
+  let hostApi
+  try {
+    hostApi = createHostApi({
+      listMachinesView: () => ({ machines: machinesForClient(), currentId: store.currentId || null }),
+      upsertMachineRecord,
+      removeMachineRecord,
+      setCurrentForApi,
+      connectMachine: connectMachineForApi,
+      probeMachineRecord,
+      statusSnapshot: () => status(),
+      resolveDirBinding: listDirBindingForApi,
+      listRemoteProjects: listRemoteProjectsForApi,
+      resolveMachine: resolveMachineForApi,
+      ensureMirror,
+      registerMirroredWorkspace,
+      checkRemoteDir: checkRemoteDirForApi,
+      workspaceRoot: remoteWorkspacesRoot,
+      sessionsRoot: () => path.join(dshBase(), 'sessions'),
+      workspaceRegistry: () => (ctx && typeof ctx.get === 'function' ? ctx.get('workspaceRegistry') : undefined),
+      forgetRemotePath,
+      isSessionLive,
+    })
+    // cordis 4: `ctx.provide(name, value)` is the raw service registry (the
+    // `Service` base class is only sugar around it). Guarded because a minimal
+    // embedding — and the test harness before it grew `provide` — has no
+    // context service registry; a bare call would abort apply.
+    if (ctx && typeof ctx.provide === 'function') {
+      try {
+        ctx.provide('dshRemote', hostApi)
+        hostLog('info', '[dsh-remote] in-process API available as ctx.dshRemote (apiVersion 1)')
+      } catch (err) {
+        hostLog('warn', `[dsh-remote] could not register ctx.dshRemote: ${String((err && err.message) || err)}`)
+      }
+    }
+  } catch (err) {
+    // The API is additive: never let it break the plugin.
+    hostLog('warn', `[dsh-remote] in-process API unavailable: ${String((err && err.message) || err)}`)
+  }
+
+  // ── TUI integration layer (dsh-tui) ───────────────────────────────────────
+  // Additive and optional: lib/tui/index.js probes its seams with
+  // `ctx.get(name, false)` and is a no-op on a Web/Desktop profile. A broken
+  // TUI layer must never take the host down, hence the guard here too.
+  //
+  // Loaded LAZILY on purpose: `lib/tui/` is the only SUBDIRECTORY under lib/,
+  // and a deployment that copies just `lib/*.js` (a hand-rolled sync, a partial
+  // unpacks) would otherwise fail at module-import time and take the whole
+  // plugin down in the Web profile as well. A missing TUI directory now means
+  // "no terminal layer", which is exactly the pre-TUI behaviour.
+  if (config.tui !== false && hostApi) {
+    import('./tui/index.js').then((mod) => {
+      if (typeof mod.installTui !== 'function') {
+        hostLog('warn', '[dsh-remote] TUI layer has no installTui export; skipped')
+        return
+      }
+      try {
+        mod.installTui(ctx, hostApi, config)
+      } catch (err) {
+        hostLog('warn', `[dsh-remote] TUI layer failed to install: ${String((err && err.message) || err)}`)
+      }
+    }).catch((err) => {
+      hostLog('warn', `[dsh-remote] TUI layer unavailable: ${String((err && err.message) || err)}`)
+    })
+  }
+}