dsh-remote-workspaces 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-workspaces",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "description": "Open folders on remote hosts over SSH as DeepSeek Harness workspaces — a non-invasive DSH bundle.",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "cordis.patch.yml"
   ],
   "scripts": {
-    "test": "node test/unit-anchor-path.mjs && node test/unit-secrets-encryption.mjs && node test/unit-fs.mjs && node test/unit-shell.mjs && node test/unit-routing.mjs && node test/unit-remote-policy.mjs && node test/unit-search-registration.mjs",
+    "test": "node test/unit-anchor-path.mjs && node test/unit-secrets-encryption.mjs && node test/unit-fs.mjs && node test/unit-shell.mjs && node test/unit-routing.mjs && node test/unit-remote-policy.mjs && node test/unit-search-registration.mjs && node test/unit-win-remote.mjs && node test/unit-registry-os.mjs",
     "test:integration": "node test/integration-remote.mjs"
   },
   "dependencies": {

package/src/client.js

@@ -809,6 +809,14 @@ window.__ModuleLoader__.load({
           '.dsh-rw-btn button:disabled{opacity:.5;cursor:not-allowed}',
           '.dsh-rw-btn button:focus-visible{outline:2px solid #6e56cf;outline-offset:2px}',
           '.dsh-rw-btn input:focus,.dsh-rw-btn select:focus{box-shadow:0 0 0 1px #6e56cf}',
+          // The host chooser sits inside the always-dark modal (modalBg #1f1f21,
+          // text #e8e8e8), but a native <select> renders its option popup on the
+          // OS theme. Without dark color-scheme the light inherited text lands on
+          // a light popup and the host list is unreadable. Force the popup dark,
+          // and give the options an explicit light-on-dark fallback.
+          '.dsh-rw-btn select{color-scheme:dark}',
+          '.dsh-rw-btn select option{color:#e8e8e8;background:#1f1f21}',
+          '.dsh-rw-btn select option:checked{background:#6e56cf;color:#fff}',
         ].join('\n')
         document.head.appendChild(styleEl)
       }

package/src/index.js

@@ -4,7 +4,7 @@ import { loadMachines, sanitizeMachine, upsertMachine, removeMachine, machineByI
 import { ensureAnchor } from './anchor.js'
 import { RoutingFileSystem } from './routing-fs.js'
 import { SshShellExecutor } from './shell-exec.js'
-import { registerAnchor, unregisterAnchor, findByCwd } from './registry.js'
+import { registerAnchor, unregisterAnchor, findByCwd, updateAnchorOs } from './registry.js'
 import { applySearchTools } from './search.js'
 
 export { parseSshConfig, expandTilde } from './ssh-config.js'
@@ -93,6 +93,13 @@ function messageOf(error) {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** Directory flag from an SFTP attrs record (protocol-level, locale-free). */
+function attrsIsDir(st) {
+  if (st && typeof st.isDirectory === 'function') return st.isDirectory()
+  if (st && typeof st.mode === 'number') return (st.mode & 0o170000) === 0o040000
+  return false
+}
+
 /**
  * Build an `SshClient` for a remote host, preferring a saved machine's
  * credentials (password/identityFile/passphrase) and falling back to
@@ -104,31 +111,71 @@ function clientForRemote(host, user, port) {
   return machine ? sshClientFor(machine) : clientForHost(host)
 }
 
+const OS_BACKFILL_QUEUED = new Set()
+
+/**
+ * Lazily backfill the `os` profile on an anchor row that predates B4 (kicked
+ * once per anchor per process, fire-and-forget). Prompt hints re-read the
+ * registry on every render, so the next prompt after the probe sees the OS.
+ */
+function kickOsBackfill(cwd) {
+  if (typeof cwd !== 'string' || cwd === '') return
+  let hit
+  try { hit = findByCwd(cwd) } catch { return }
+  if (hit === undefined || (hit.os && hit.os.family !== undefined)) return
+  if (OS_BACKFILL_QUEUED.has(hit.anchorPath)) return
+  OS_BACKFILL_QUEUED.add(hit.anchorPath)
+  void (async () => {
+    try {
+      const client = clientForRemote(hit.host, hit.user, hit.port)
+      const profile = await client.profile()
+      if (profile !== undefined && (profile.family === 'posix' || profile.family === 'windows')) {
+        updateAnchorOs(hit.anchorPath, { family: profile.family, os: profile.os, shell: profile.shell })
+        return
+      }
+      // Unknown / undetectable: leave the dedupe queue so the NEXT prompt
+      // render re-kicks the probe (failed probes are not cached, so a later
+      // attempt really does re-probe instead of reusing a stale unknown).
+      OS_BACKFILL_QUEUED.delete(hit.anchorPath)
+      console.warn(`[dsh-remote-workspaces] os backfill probe failed for ${hit.host} (family unknown); will retry on next render`)
+    } catch (error) {
+      OS_BACKFILL_QUEUED.delete(hit.anchorPath)
+      console.warn(`[dsh-remote-workspaces] os backfill probe errored for ${hit.host}: ${messageOf(error)}`)
+    }
+  })()
+}
+
 /**
  * Resolve a raw browse path (home, `~`, `~/x`, relative, or absolute) to an
  * absolute remote path so the client can navigate "up" past home to `/` and
- * display a real path.
+ * display a real path. Accepts an optional open SFTP facade to reuse across
+ * resolve + listing; otherwise opens its own channel. Resolution goes over
+ * SFTP (`realpath`), so it works identically on POSIX and Windows targets and
+ * never parses localized shell output.
  */
-async function resolveRemotePath(client, raw) {
+async function resolveRemotePath(client, raw, sharedSftp) {
   const trimmed = raw === undefined || raw === null ? '' : String(raw).trim()
-  let sftp
+  let owned
+  const sftp = async () => {
+    if (sharedSftp !== undefined) return sharedSftp
+    owned = owned ?? await client.sftp()
+    return owned
+  }
   try {
     if (trimmed === '' || trimmed === '~' || trimmed === '~/') {
-      sftp = await client.sftp()
-      return await sftp.realpath('.')
+      return await (await sftp()).realpath('.')
     }
     if (trimmed.startsWith('~/')) {
-      sftp = await client.sftp()
-      const home = String(await sftp.realpath('.')).replace(/\/+$/, '')
+      const s = await sftp()
+      const home = String(await s.realpath('.')).replace(/\/+$/, '')
       return `${home}/${trimmed.slice(2)}`
     }
     if (!trimmed.startsWith('/')) {
-      sftp = await client.sftp()
-      return await sftp.realpath(trimmed)
+      return await (await sftp()).realpath(trimmed)
     }
     return trimmed
   } finally {
-    if (sftp) sftp.end()
+    if (owned !== undefined) owned.end()
   }
 }
 
@@ -183,22 +230,35 @@ function remoteWorkspacesService() {
     },
 
     async listRemoteDir(machine, path) {
-      // `-A` hides `.`/`..`, `-p` appends `/` to directories, `-1` one per line.
+      // Pure-SFTP listing (readdir + attrs) — the SAME channel the fs backend
+      // uses, so Windows targets work: no `ls`, no localized output parsing,
+      // no dependency on the remote's default shell.
       const client = sshClientFor(machine)
-      let absPath
+      let sftp
       try {
-        absPath = await resolveRemotePath(client, path)
+        sftp = await client.sftp()
+      } catch (error) {
+        return { ok: false, error: `无法建立 SFTP 连接：${messageOf(error)}` }
+      }
+      try {
+        const absPath = await resolveRemotePath(client, path, sftp)
+        let list
+        try {
+          list = await sftp.readdir(absPath)
+        } catch (error) {
+          const missing = error && (error.code === 2 || /no such file|not exist|找不到/i.test(String(error.message)))
+          return { ok: false, error: missing ? `目录不存在：${absPath}` : `无法读取目录：${messageOf(error)}` }
+        }
+        const entries = (Array.isArray(list) ? list : [])
+          .filter((e) => e && e.filename !== '.' && e.filename !== '..')
+          .map((e) => ({ name: e.filename, dir: attrsIsDir(e.attrs) }))
+          .sort((a, b) => a.name.localeCompare(b.name))
+        return { ok: true, entries, path: absPath }
       } catch (error) {
         return { ok: false, error: `无法解析目录：${messageOf(error)}` }
+      } finally {
+        sftp.end()
       }
-      const command = absPath === '' ? 'ls -1Ap' : `ls -1Ap ${shellQuote(absPath)}`
-      const res = await client.run(command)
-      if (!res.ok) return { ok: false, error: (res.stderr ?? '').trim() || res.error || '列出目录失败' }
-      const entries = res.stdout
-        .split('\n')
-        .filter((name) => name !== '')
-        .map((name) => ({ name: name.replace(/\/$/, ''), dir: name.endsWith('/') }))
-      return { ok: true, entries, path: absPath }
     },
 
     /**
@@ -220,6 +280,16 @@ function remoteWorkspacesService() {
         const rel = path === undefined || path === '' ? '.' : path
         const remotePath = await sftp.realpath(rel)
         const anchorPath = ensureAnchor(machine, remotePath)
+        // Probe the remote profile once so prompt/dialect hints can declare
+        // the actual shell (PowerShell on Windows remotes). Failure to probe
+        // only leaves the hint off — never fails the open.
+        let os
+        try {
+          const profile = await client.profile()
+          if (profile !== undefined && (profile.family === 'posix' || profile.family === 'windows')) {
+            os = { family: profile.family, os: profile.os, shell: profile.shell }
+          }
+        } catch { /* os stays undefined */ }
         registerAnchor({
           anchorPath,
           machineId: machine?.id,
@@ -227,6 +297,7 @@ function remoteWorkspacesService() {
           port: machine?.port ?? null,
           user: machine?.user ?? null,
           remotePath,
+          ...(os !== undefined ? { os } : {}),
         })
         return { ok: true, localDir: anchorPath, remotePath }
       } catch (error) {
@@ -285,6 +356,8 @@ export function apply(ctx) {
         if (typeof cwd !== 'string' || cwd === '') return cwd
         const hit = findByCwd(cwd)
         if (hit === undefined) return cwd
+        // Side effect: backfill the os profile on rows registered before B4.
+        kickOsBackfill(cwd)
         return hit.remoteSubpath === '' ? hit.remotePath : `${hit.remotePath.replace(/\/+$/, '')}/${hit.remoteSubpath}`
       })
     })
@@ -303,8 +376,14 @@ export function apply(ctx) {
         if (typeof cwd !== 'string' || cwd === '') return ''
         const hit = findByCwd(cwd)
         if (hit === undefined) return ''
+        // Side effect: backfill the os profile on rows registered before B4.
+        kickOsBackfill(cwd)
         const host = hit.user ? `${hit.user}@${hit.host}` : hit.host
-        return `Remote workspace over SSH (${host}): file/search tools and shell commands run on the remote host; use relative paths (they route to the remote automatically).`
+        const base = `Remote workspace over SSH (${host}): file/search tools and shell commands run on the remote host; use relative paths (they route to the remote automatically).`
+        if (hit.os?.family === 'windows') {
+          return base + ' The remote shell is PowerShell — write PowerShell syntax (built-in aliases like ls/cat/cd/pwd work; bash-only syntax such as && or 2>/dev/null does not).'
+        }
+        return base
       },
     })
   })

package/src/registry.js

@@ -34,14 +34,28 @@ function saveAnchors(anchors) {
   writeFileSync(anchorsPath(), JSON.stringify(anchors, null, 2) + '\n', 'utf8')
 }
 
-/** Record an anchor (idempotent by anchorPath). Returns the stored record. */
-export function registerAnchor({ anchorPath, machineId, host, port, user, remotePath }) {
+/** Record an anchor (idempotent by anchorPath). Returns the stored record.
+ * `os` (optional) is the probed remote profile `{ family, os, shell }` used
+ * by prompt/dialect hints; older rows without it are backfilled lazily. */
+export function registerAnchor({ anchorPath, machineId, host, port, user, remotePath, os }) {
   const anchors = loadAnchors()
-  anchors[anchorPath] = { machineId, host, port, user, remotePath, registeredAt: new Date().toISOString() }
+  const rec = { machineId, host, port, user, remotePath, registeredAt: new Date().toISOString() }
+  if (os !== undefined && os !== null) rec.os = os
+  anchors[anchorPath] = rec
   saveAnchors(anchors)
   return anchors[anchorPath]
 }
 
+/** Backfill (or replace) the probed remote profile on an existing anchor row. */
+export function updateAnchorOs(anchorPath, os) {
+  const anchors = loadAnchors()
+  const rec = anchors[anchorPath]
+  if (rec === undefined) return undefined
+  rec.os = os
+  saveAnchors(anchors)
+  return rec
+}
+
 /** Remove one anchor by its local path. */
 export function unregisterAnchor(anchorPath) {
   const anchors = loadAnchors()
@@ -73,4 +87,4 @@ export function findByCwd(cwd) {
   return { ...best, remoteSubpath: rel === '' ? '' : rel.split(sep).join('/') }
 }
 
-export default { loadAnchors, registerAnchor, unregisterAnchor, findByCwd, remoteWorkspacesRoot }
+export default { loadAnchors, registerAnchor, unregisterAnchor, updateAnchorOs, findByCwd, remoteWorkspacesRoot }

package/src/search.js

@@ -11,7 +11,7 @@
  */
 
 import { posix } from 'node:path'
-import { shellQuote } from './transport.js'
+import { shellQuote, psQuote, toWinPath, profileCacheKey } from './transport.js'
 import { findByCwd } from './registry.js'
 
 const GREP_MAX_MATCHES = 250
@@ -21,6 +21,9 @@ const SEARCH_TIMEOUT_MS = 30_000
 const STDERR_MAX_BYTES = 64 * 1024
 const GRACE_MS = 3_000
 
+/** One-time rg-presence verdict per Windows target (process lifetime). */
+const RG_PRESENCE_CACHE = new Map()
+
 // ---------------------------------------------------------------------------
 // ripgrep argv (mirrors @deepseek-ai/dsh-tool-fs-search)
 // ---------------------------------------------------------------------------
@@ -108,11 +111,57 @@ async function localRg(deps, argv, cwd, signal) {
   if (outcome.exitCode !== 0 && outcome.exitCode !== 1) {
     throw new Error(`grep/glob: rg failed (exit ${outcome.exitCode}): ${stderr?.text ?? ''}`)
   }
-  return stdout?.text ?? ''
+  return { stdout: stdout?.text ?? '', windows: false }
+}
+
+/**
+ * Build the remote `rg` command line for one profile. POSIX keeps the legacy
+ * single-quoted form. Windows runs rg.exe inside the per-shell PowerShell
+ * script, so EVERY token is PowerShell-single-quoted (patterns with spaces or
+ * apostrophes stay one argument) and the search root — the token after `--`,
+ * which arrives in the canonical `/X:/…` SFTP form — is converted with
+ * `toWinPath` because native rg.exe does not understand a leading-slash drive
+ * path. `--path-separator=/` forces forward-slash paths in rg's JSON/file
+ * output, matching every other path the plugin surfaces (native rg.exe would
+ * otherwise print `src\file.js`). `--regexp`/`--glob` values are pattern text
+ * and pass through as-is.
+ */
+export function remoteRgCommand(profile, argv) {
+  if (profile !== undefined && profile.family === 'windows') {
+    const parts = [psQuote('--path-separator=/')]
+    let isRoot = false
+    for (const token of argv) {
+      parts.push(isRoot ? psQuote(toWinPath(token)) : psQuote(token))
+      isRoot = token === '--'
+    }
+    return `rg ${parts.join(' ')}`
+  }
+  return ['rg', ...argv].map(shellQuote).join(' ')
+}
+
+/**
+ * Verify ripgrep exists on a Windows target once per process. A missing `rg`
+ * must NOT surface as the glue's exit 1 (which the caller reads as "no
+ * matches"), so it is detected up front and reported with an install hint.
+ */
+async function ensureRemoteRg(client) {
+  const key = profileCacheKey(client)
+  let present = RG_PRESENCE_CACHE.get(key)
+  if (present === undefined) {
+    const probe = await client.run('rg --version')
+    present = probe.ok
+    RG_PRESENCE_CACHE.set(key, present)
+  }
+  if (!present) {
+    throw new Error('grep/glob: ripgrep was not found on the remote Windows host. Install it first (e.g. winget install BurntSushi.ripgrep.MSVC or scoop install ripgrep) and retry')
+  }
 }
 
 async function remoteRg(client, argv, remoteCwd, signal) {
-  const command = ['rg', ...argv].map(shellQuote).join(' ')
+  const profile = await client.profile()
+  const windows = profile.family === 'windows'
+  if (windows) await ensureRemoteRg(client)
+  const command = remoteRgCommand(profile, argv)
   const result = await client.execShell(command, {
     cwd: remoteCwd,
     timeoutMs: SEARCH_TIMEOUT_MS,
@@ -124,7 +173,16 @@ async function remoteRg(client, argv, remoteCwd, signal) {
   if (result.exitCode !== 0 && result.exitCode !== 1) {
     throw new Error(`grep/glob: remote rg failed (exit ${result.exitCode}): ${result.stderr.text}`)
   }
-  return result.stdout.text
+  return { stdout: result.stdout.text, windows }
+}
+
+/**
+ * rg.exe ignores `--path-separator` for the JSON match records it emits, so
+ * grep paths come back with native backslashes on Windows remotes. Normalize
+ * to forward slashes so every surfaced path matches the canonical form.
+ */
+function normalizeWindowsPath(value) {
+  return String(value).replace(/\\/g, '/')
 }
 
 // ---------------------------------------------------------------------------
@@ -216,8 +274,13 @@ export function createSearchTools(deps) {
         ...(args.path !== undefined ? { path: args.path } : {}),
         ...(args.include !== undefined ? { include: args.include } : {}),
       }
-      const stdout = await runRg(exec, grepArgv, input)
-      return { matches: parseGrepMatches(stdout).slice(0, GREP_MAX_MATCHES) }
+      const { stdout, windows } = await runRg(exec, grepArgv, input)
+      const matches = parseGrepMatches(stdout).slice(0, GREP_MAX_MATCHES)
+      return {
+        matches: windows
+          ? matches.map((m) => ({ ...m, path: normalizeWindowsPath(m.path) }))
+          : matches,
+      }
     },
   }
 
@@ -248,8 +311,9 @@ export function createSearchTools(deps) {
     },
     async execute(args, exec) {
       const input = { pattern: args.pattern, ...(args.path !== undefined ? { path: args.path } : {}) }
-      const stdout = await runRg(exec, globArgv, input)
-      return { paths: parseGlobPaths(stdout).slice(0, GLOB_MAX_RESULTS) }
+      const { stdout, windows } = await runRg(exec, globArgv, input)
+      const paths = parseGlobPaths(stdout).slice(0, GLOB_MAX_RESULTS)
+      return { paths: windows ? paths.map(normalizeWindowsPath) : paths }
     },
   }
 

package/src/shell-exec.js

@@ -9,7 +9,7 @@
  * harness's `bash-sandbox`/`pwsh-sandbox` apply).
  */
 
-import { SshClient, shellQuote } from './transport.js'
+import { SshClient, shellQuote, PROBE_UNKNOWN_MSG } from './transport.js'
 import { isRemoteCwd, parseSshUri } from './ssh-uri.js'
 import { findByCwd } from './registry.js'
 import { lstatSync } from 'node:fs'
@@ -226,6 +226,7 @@ export class SshShellExecutor {
     let buffer = ''
     let spawnError
     let pollTimer
+    let streamCtl = null
 
     const proc = {
       status: 'running',
@@ -240,10 +241,62 @@ export class SshShellExecutor {
       kill() {
         if (proc.status !== 'running') return false
         proc.status = 'killed'
-        if (pid !== null) void client.run(`kill ${pid} 2>/dev/null || true`)
+        if (streamCtl !== null) streamCtl.terminate()
+        else if (pid !== null) void client.run(`kill ${pid} 2>/dev/null || true`)
         return true
       },
       done: (async () => {
+        const profile = await client.profile()
+        if (profile.family === 'unknown') {
+          // Never run the POSIX nohup launcher against an undetected host (a
+          // Windows/cmd host would die on the `cd '…'` line with Win32 123).
+          spawnError = new Error(PROBE_UNKNOWN_MSG)
+          proc.status = 'killed'
+          return
+        }
+        if (profile.family === 'windows') {
+          // No nohup-style detach exists on Windows remotes, and closing the
+          // channel alone does NOT reap the remote tree (verified) - so the
+          // job is a long-lived exec stream whose terminate() actively
+          // taskkill /T's the remote PID and then closes the channel.
+          const ctl = await client.execStream(spec.command, { cwd: path })
+          if (proc.status !== 'running') { ctl.terminate(); return }
+          streamCtl = ctl
+          const merge = () => {
+            const outPart = ctl.readOut()
+            const errPart = ctl.readErr()
+            if (outPart.delta.length > 0) {
+              if (buffer.length > 0 && !buffer.endsWith('\n')) buffer += '\n'
+              buffer += outPart.delta
+            }
+            if (errPart.delta.length > 0) {
+              if (buffer.length > 0 && !buffer.endsWith('\n')) buffer += '\n'
+              buffer += '[stderr]\n' + errPart.delta
+            }
+          }
+          if (spec.signal !== undefined) {
+            const onAbort = () => { if (streamCtl !== null) streamCtl.terminate() }
+            if (spec.signal.aborted) onAbort()
+            else spec.signal.addEventListener('abort', onAbort, { once: true })
+          }
+          const pump = async () => {
+            while (proc.status === 'running') {
+              merge()
+              await new Promise((r) => setTimeout(r, 150))
+            }
+          }
+          void pump()
+          const outcome = await ctl.exit
+          merge()
+          if (proc.status === 'running') proc.status = 'completed'
+          if (outcome.error !== undefined) {
+            spawnError = new Error(outcome.error)
+            proc.status = 'killed'
+            return
+          }
+          proc.exitCode = typeof outcome.exitCode === 'number' ? outcome.exitCode : null
+          return
+        }
         const launched = await client.run(launchScript)
         if (!launched.ok) {
           spawnError = new Error((launched.stderr ?? '').trim() || launched.error || 'background spawn failed')

package/src/transport.js

@@ -12,6 +12,195 @@ export function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`
 }
 
+/**
+ * Convert a canonical REMOTE path — as the SFTP `realpath` reports it, which
+ * is POSIX-style even on Windows hosts (`/X:/work/demo`) — into the form a
+ * Windows shell accepts (`X:/work/demo`). PowerShell understands forward
+ * slashes, so only a leading `/X:` drive prefix is stripped; everything else
+ * passes through untouched.
+ */
+export function toWinPath(value) {
+  const s = String(value ?? '')
+  return /^\/[A-Za-z]:/.test(s) ? s.slice(1) : s
+}
+
+/** PowerShell single-quote escaping for a path/string literal. */
+export function psQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}
+
+/**
+ * Strip PowerShell progress records from a stderr capture. When a nested
+ * powershell is launched by a Windows OpenSSH exec channel (e.g. the cmd
+ * default-shell wrapper), the engine's first-run module-analysis warm-up emits
+ * a `#< CLIXML …</Objs>` progress blob to stderr on every fresh process —
+ * real cmdlet errors still arrive as plain text, so removing only CLIXML
+ * blocks keeps genuine diagnostics intact.
+ */
+export function stripPsProgressClixml(text) {
+  const lines = String(text ?? '').split('\n')
+  const out = []
+  let inBlob = false
+  for (const line of lines) {
+    if (!inBlob && /#< CLIXML/i.test(line)) {
+      inBlob = !/<\/Objs>/i.test(line)
+      continue
+    }
+    if (inBlob) {
+      if (/<\/Objs>/i.test(line)) { inBlob = false; continue }
+      // XML record lines are dropped; a non-XML text line ends a truncated
+      // blob so genuine diagnostics that follow it are preserved.
+      if (!/^\s*</.test(line) && line.trim() !== '') { inBlob = false; out.push(line); continue }
+      continue
+    }
+    out.push(line)
+  }
+  return out.join('\n')
+}
+
+/** Whole-text CRLF→LF (Windows remote output normalization). */
+export function crlfToLf(text) {
+  return String(text ?? '').replace(/\r\n/g, '\n')
+}
+
+/**
+ * Streaming CRLF→LF normalizer that carries a trailing `\r` across chunk
+ * boundaries (a `\r\n` pair may be split between two data events). `feed`
+ * returns the normalized fragment; call `flush()` at stream end for a lone
+ * trailing `\r` (isolated CRs are preserved, not folded).
+ */
+export function createCrlfToLf() {
+  let carry = ''
+  return {
+    feed(text) {
+      const s = String(text ?? '')
+      let out = carry + s
+      carry = ''
+      out = out.replace(/\r\n/g, '\n')
+      if (out.endsWith('\r')) {
+        carry = '\r'
+        out = out.slice(0, -1)
+      }
+      return out
+    },
+    flush() {
+      const rest = carry
+      carry = ''
+      return rest
+    },
+  }
+}
+
+/**
+ * Exit-code glue appended to every Windows remote script so the channel's
+ * exit status mirrors what a POSIX shell reports: the last command's result.
+ * `exit N` inside the user's own command terminates first and wins.
+ */
+const PS_EXIT_GLUE = 'if ($?) { exit $LASTEXITCODE } else { exit 1 }'
+
+/**
+ * Remote execution profiles, probed once per target and cached for the
+ * process lifetime:
+ *   { family: 'posix',  os: 'linux'|'darwin', shell: 'posix' }
+ *   { family: 'windows', os: 'windows', shell: 'powershell'|'cmd' }
+ *   { family: 'unknown', … } — callers fall back to POSIX behaviour.
+ */
+const REMOTE_PROFILE_CACHE = new Map()
+
+export function profileCacheKey({ host, user, port }) {
+  return `${user ?? ''}@${host ?? ''}:${port ?? 22}`
+}
+
+/**
+ * Detect a target's OS family and default exec shell without parsing
+ * localized output: `uname -s` proves a POSIX shell; the bare `ver` builtin
+ * proves a cmd-default Windows host; a quoted nested `cmd /c "ver"` proves
+ * Windows under a PowerShell default (PowerShell itself has no `ver`); a
+ * `$PSVersionTable` expression then tells cmd from PowerShell as the default.
+ *
+ * Quoting matters on real cmd-default Windows hosts: OpenSSH wraps the exec
+ * payload for cmd.exe in a way that mangles inner unquoted spaces — `cmd /c
+ * ver` arrives as `ver"` and fails, while a bare single token (`ver`) and a
+ * quoted inner command (`cmd /c "ver"`) both pass (verified on a real host).
+ */
+export async function probeRemoteProfile(client) {
+  const uname = await client.run('uname -s')
+  if (uname.ok) {
+    const os = (uname.stdout ?? '').trim().toLowerCase()
+    return { family: 'posix', os: os.startsWith('darwin') ? 'darwin' : 'linux', shell: 'posix' }
+  }
+  const ver = await client.run('ver')
+  if (ver.ok) return { family: 'windows', os: 'windows', shell: 'cmd' }
+  const nested = await client.run('cmd /c "ver"')
+  if (nested.ok && /windows/i.test(nested.stdout ?? '')) {
+    const ps = await client.run('$PSVersionTable.PSVersion.ToString()')
+    return ps.ok
+      ? { family: 'windows', os: 'windows', shell: 'powershell' }
+      : { family: 'windows', os: 'windows', shell: 'cmd' }
+  }
+  const ps = await client.run('$PSVersionTable.PSVersion.ToString()')
+  if (ps.ok) return { family: 'windows', os: 'windows', shell: 'powershell' }
+  return { family: 'unknown', os: 'unknown', shell: 'unknown' }
+}
+
+/**
+ * Error text used whenever a command cannot run because the remote profile
+ * probe failed (family 'unknown'). Explicit instead of guessing a dialect:
+ * sending a POSIX `cd 'x' || exit 1` script to a Windows/cmd host produces the
+ * misleading "文件名、目录名或卷标语法不正确" (Win32 123) failure, and the
+ * other way around is equally wrong — so callers refuse loudly.
+ */
+export const PROBE_UNKNOWN_MSG =
+  'cannot determine the remote shell type (exec probe failed); command not executed. Check the host side: the account home/profile directory must exist, the OpenSSH DefaultShell must be valid, and the exec channel itself must be usable.'
+
+/** Encode a PowerShell script for quote-safe transport through cmd.exe.
+ *
+ * `powershell -EncodedCommand` would be ideal (no quoting at all), but a
+ * nested -EncodedCommand host serializes BOTH progress and error records to
+ * stderr as CLIXML soup. A `-Command` host prints plain text, so instead the
+ * script rides inside one fixed, quote-free command line: base64 has no
+ * `% ! ^ " $ '` and the wrapper has no `$`, so neither cmd nor a PowerShell
+ * outer shell can mangle it, and the inner text is decoded + `iex`'d.
+ */
+export function psCommandEnvelope(script) {
+  const b64 = Buffer.from(script, 'utf16le').toString('base64')
+  return `powershell -NoProfile -NonInteractive -Command "& { iex ([Text.Encoding]::Unicode.GetString([Convert]::FromBase64String('${b64}'))) }"`
+}
+
+/**
+ * Build the exec-channel script for one command under a remote profile.
+ *
+ * POSIX / unknown: unchanged legacy form (`cd 'x' || exit 1` + command).
+ *
+ * Windows with a PowerShell default shell: the raw script text is executed
+ * by the server's default shell directly (cmdlets + aliases like ls/cat/cd
+ * make simple commands work), prefixed with a `Set-Location` when a cwd is
+ * given and suffixed with the exit-code glue. Windows with a cmd default
+ * shell: the same script rides inside a fixed, quote-free
+ * `powershell -Command` envelope (base64 + iex), so cmd only ever parses one
+ * fixed command line, its exit code is the child's, and stderr stays plain
+ * text (no CLIXML records).
+ */
+export function buildExecScript(profile, command, cwd) {
+  if (profile === undefined) {
+    return cwd ? `cd ${shellQuote(cwd)} || exit 1\n${command}` : command
+  }
+  if (profile.family === 'unknown') {
+    // Never guess: a POSIX script against a Windows/cmd host dies on the first
+    // line with Win32 123-style errors and never reaches the command.
+    throw new Error(PROBE_UNKNOWN_MSG)
+  }
+  if (profile.family !== 'windows') {
+    return cwd ? `cd ${shellQuote(cwd)} || exit 1\n${command}` : command
+  }
+  const script = [
+    ...(cwd ? [`Set-Location -LiteralPath ${psQuote(toWinPath(cwd))}`] : []),
+    command,
+    PS_EXIT_GLUE,
+  ].join('\n')
+  return profile.shell === 'cmd' ? psCommandEnvelope(script) : script
+}
+
 /** Bounded output collector: keeps the TAIL of a stream, flags truncation. */
 class CapCollector {
   constructor(maxBytes) {
@@ -193,9 +382,18 @@ export class SshClient {
    * bounded (tail-kept) stdout/stderr, stdin, and an abort signal that closes
    * the exec channel (SIGHUP on the remote). Resolves with exitCode/signal,
    * timedOut/aborted first-cause, and `{ text, truncated }` outputs.
+   *
+   * The command text is executed through the target's default shell. On
+   * Windows targets the script is built per detected default shell
+   * (`buildExecScript`): raw PowerShell when PowerShell is the default, a
+   * quote-safe `powershell -EncodedCommand` wrapper when cmd is.
    */
   async execShell(command, { cwd, timeoutMs = 60000, stdoutMaxBytes = 64000, stderrMaxBytes = 64000, stdin, signal } = {}) {
-    const script = cwd ? `cd ${shellQuote(cwd)} || exit 1\n${command}` : command
+    const profile = await this.profile()
+    if (profile.family === 'unknown') {
+      return { ok: false, error: PROBE_UNKNOWN_MSG }
+    }
+    const script = buildExecScript(profile, command, cwd)
     return await new Promise((resolve) => {
       const conn = new Client()
       let settled = false
@@ -228,14 +426,20 @@ export class SshClient {
           s.stderr.on('data', (d) => errc.push(d))
           s.on('close', (code) => {
             const aborted = signal !== undefined && signal.aborted
+            const stdout = out.output()
+            const stderr = errc.output()
+            if (profile.family === 'windows') {
+              stderr.text = crlfToLf(stripPsProgressClixml(stderr.text))
+              stdout.text = crlfToLf(stdout.text)
+            }
             finish({
               ok: true,
               exitCode: code,
               signal: null,
               timedOut: timedOut && !aborted,
               aborted: aborted && !timedOut,
-              stdout: out.output(),
-              stderr: errc.output(),
+              stdout,
+              stderr,
             })
           })
           if (stdin === undefined) s.end()
@@ -293,10 +497,178 @@ export class SshClient {
     })
   }
 
+  /**
+   * Open a LONG-LIVED exec channel for streaming (used by background/start
+   * jobs on Windows remotes, where no nohup-style detach exists and closing
+   * the channel alone does NOT reliably reap the remote command tree — a kill
+   * must actively `taskkill /T` the remote process first; the channel close
+   * is only a fallback).
+   *
+   * On Windows the remote script is prefixed with a self-reporting PID line
+   * (`DWSH_PID=<pid>`), which is parsed out of the first output chunk so the
+   * controller can tree-kill the exact process. Resolves a controller:
+   *   { readOut(), readErr() -> { delta, lossy }, exit: Promise<{exitCode}|{error}>, terminate() }
+   */
+  async execStream(command, { cwd, signal, stdoutMaxBytes = 16 * 1024 * 1024, stderrMaxBytes = 16 * 1024 * 1024 } = {}) {
+    const profile = await this.profile()
+    if (profile.family === 'unknown') {
+      // Same explicit refusal as execShell: no dialect to build the script in.
+      return {
+        readOut: () => ({ delta: '', lossy: false }),
+        readErr: () => ({ delta: '', lossy: false }),
+        exit: Promise.resolve({ error: PROBE_UNKNOWN_MSG }),
+        terminate() {},
+      }
+    }
+    const windows = profile.family === 'windows'
+    const ssh = this
+    // The marker runs FIRST inside the same remote shell that owns the exec
+    // channel (the raw PowerShell on PS-default hosts, the nested PowerShell
+    // inside the -Command envelope on cmd-default hosts), so its $PID is the
+    // process whose tree taskkill must reap.
+    const markerCommand = windows ? "Write-Output ('DWSH_PID=' + $PID)\n" + command : command
+    const script = buildExecScript(profile, markerCommand, cwd)
+    return await new Promise((resolve, reject) => {
+      const conn = new Client()
+      const out = { buf: '', pos: 0, max: stdoutMaxBytes, lossy: false }
+      const err = { buf: '', pos: 0, max: stderrMaxBytes, lossy: false }
+      let stream
+      let settled = false
+      let pidResolve
+      const pid = new Promise((res) => { pidResolve = res })
+      // A stuck launch must not hold terminate() forever.
+      const pidTimer = setTimeout(() => pidResolve(null), 8000)
+      let exitResolve
+      const exit = new Promise((res) => { exitResolve = res })
+      const finish = (value) => {
+        if (settled) return
+        settled = true
+        clearTimeout(pidTimer)
+        try { conn.end() } catch {}
+        exitResolve(value)
+      }
+      const push = (target) => (chunk) => {
+        const piece = String(chunk)
+        if (target.buf.length + piece.length > target.max) { target.lossy = true; return }
+        target.buf += piece
+      }
+      const reader = (target) => () => {
+        const delta = target.buf.slice(target.pos)
+        target.pos = target.buf.length
+        return { delta, lossy: target.lossy }
+      }
+      // Normalize Windows CRLF output to LF at the chunk boundary so a \r\n
+      // split across data events still folds (isolated CRs are preserved).
+      const outLf = windows ? createCrlfToLf() : null
+      const errLf = windows ? createCrlfToLf() : null
+      // The PID marker is the FIRST stdout line, but the first data chunk may
+      // hold only part of it, so buffer head bytes until the line completes.
+      let head = ''
+      let markerResolved = false
+      const onOut = (chunk) => {
+        const text = outLf === null ? String(chunk) : outLf.feed(chunk)
+        if (text === '') return
+        if (markerResolved) { push(out)(text); return }
+        head += text
+        if (windows) {
+          const m = /^DWSH_PID=(\d+)\r?\n/.exec(head)
+          if (m !== null) {
+            markerResolved = true
+            clearTimeout(pidTimer)
+            pidResolve(Number(m[1]))
+            const rest = head.slice(m[0].length)
+            head = ''
+            if (rest.length > 0) push(out)(rest)
+            return
+          }
+          if (head.length > 4096) {
+            // Something else produced output first; give up on the marker.
+            markerResolved = true
+            clearTimeout(pidTimer)
+            pidResolve(null)
+            push(out)(head)
+            head = ''
+          }
+          return
+        }
+        markerResolved = true
+        clearTimeout(pidTimer)
+        pidResolve(null)
+        push(out)(head)
+        head = ''
+      }
+      const onErr = (chunk) => {
+        const text = errLf === null ? String(chunk) : errLf.feed(chunk)
+        if (text !== '') push(err)(text)
+      }
+      conn.on('ready', () => {
+        conn.exec(script, (execError, s) => {
+          if (execError) { finish({ error: execError.message }); return }
+          stream = s
+          s.on('data', onOut)
+          s.stderr.on('data', onErr)
+          s.on('close', (code) => {
+            if (outLf !== null) { const rest = outLf.flush(); if (rest !== '') push(out)(rest) }
+            if (errLf !== null) { const rest = errLf.flush(); if (rest !== '') push(err)(rest) }
+            finish({ exitCode: code })
+          })
+          s.end()
+        })
+      })
+      conn.on('error', (connError) => finish({ error: connError.message }))
+      try { conn.connect(this.connectConfig()) } catch (connectError) { finish({ error: connectError.message }) }
+      resolve({
+        readOut: reader(out),
+        readErr: reader(err),
+        exit,
+        terminate() {
+          const doClose = () => {
+            try { if (stream) stream.close() } catch {}
+            try { conn.end() } catch {}
+            // Settle explicitly: the remote 'close' event is not guaranteed.
+            finish({ exitCode: null })
+          }
+          pid.then((remotePid) => {
+            if (typeof remotePid === 'number' && remotePid > 0) {
+              void ssh.execShell(`taskkill /PID ${remotePid} /T /F`, {
+                timeoutMs: 15000, stdoutMaxBytes: 4096, stderrMaxBytes: 4096,
+              }).catch(() => {}).finally(doClose)
+            } else {
+              doClose()
+            }
+          })
+        },
+      })
+    })
+  }
+
+  /**
+   * Cached remote execution profile ({ family, os, shell }); probed once per
+   * target and reused for the process lifetime. FAILED probes (family
+   * 'unknown') are never cached, so the next call re-probes: a transient
+   * failure or a host-side fix is picked up without restarting the process.
+   */
+  async profile() {
+    const key = profileCacheKey(this)
+    let profile = REMOTE_PROFILE_CACHE.get(key)
+    if (profile === undefined) {
+      profile = await probeRemoteProfile(this)
+      if (profile.family === 'posix' || profile.family === 'windows') {
+        REMOTE_PROFILE_CACHE.set(key, profile)
+      }
+    }
+    return profile
+  }
+
   async remoteOs() {
     if (this._os === undefined) {
-      const res = await this.run('uname -s')
-      this._os = (res.stdout ?? '').trim().toLowerCase().startsWith('darwin') ? 'darwin' : 'linux'
+      const profile = await this.profile()
+      if (profile.family === 'posix') this._os = profile.os === 'darwin' ? 'darwin' : 'linux'
+      else if (profile.family === 'windows') this._os = 'windows'
+      else {
+        const res = await this.run('uname -s')
+        this._os = (res.stdout ?? '').trim().toLowerCase().startsWith('darwin') ? 'darwin' : 'linux'
+      }
     }
     return this._os
   }
@@ -383,12 +755,25 @@ export class SshClient {
   }
 
   /**
-   * Remote file content hash for post-write verification. Tries GNU
-   * `sha256sum` then BSD `shasum -a 256`; returns the lowercase hex digest or
+   * Remote file content hash for post-write verification. On POSIX targets
+   * tries GNU `sha256sum` then BSD `shasum -a 256`; on Windows targets uses
+   * PowerShell `Get-FileHash`. Returns the lowercase hex digest or
    * `undefined` when no such tool exists (verification is then skipped).
    * Locale-independent: the digest is hex, never localized text.
    */
   async sha256(path) {
+    const profile = await this.profile()
+    if (profile.family === 'windows') {
+      const res = await this.execShell(
+        `(Get-FileHash -LiteralPath ${psQuote(toWinPath(path))} -Algorithm SHA256).Hash.ToLower()`,
+        { timeoutMs: 30000 },
+      )
+      if (res.exitCode === 0) {
+        const hash = (res.stdout?.text ?? '').trim().toLowerCase()
+        if (/^[0-9a-f]{64}$/.test(hash)) return hash
+      }
+      return undefined
+    }
     for (const cmd of [`sha256sum ${shellQuote(path)}`, `shasum -a 256 ${shellQuote(path)}`]) {
       const res = await this.run(`${cmd} 2>/dev/null`)
       if (res.ok) {