dsh-winrm 0.2.0 → 0.3.1

package/lib/index.js

@@ -1,8 +1,11 @@
+import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
+import { createGunzip, gzipSync } from "node:zlib";
 import { Command, Shell } from "winrm-client";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { copyFile, readFile, stat, unlink } from "node:fs/promises";
-import { createHash, randomBytes } from "node:crypto";
+import { createConnection } from "node:net";
 import { closeSync, createReadStream, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
@@ -143,6 +146,55 @@ function powershellCommandLine() {
 	return "powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand " + encodeCommand(OUTER_SCRIPT);
 }
 /**
+* Bootstrap for the streaming upload path: read `<byteCount>\n<script>` from
+* stdin, then run that script **in this process** so it can keep draining the
+* same stdin stream.
+*
+* This exists because {@link psReceiveStream} outgrew the command line. WinRS
+* hands the command line to cmd.exe, whose limit is about 8191 characters, and
+* the receiver is 3424 characters of PowerShell — 9206 once base64-of-UTF-16
+* expands it, over the cap. Shipping the receiver on stdin instead costs one
+* extra `Send` and keeps the command line a constant 1154 characters no matter
+* how the receiver grows.
+*
+* Running the receiver in-process (rather than in a child, as
+* {@link OUTER_SCRIPT} does) is what makes the handoff work: the child would
+* need its own stdin, and the payload has to keep flowing into whatever reads
+* the file. A fresh `[Console]::OpenStandardInput()` inside the receiver picks
+* up exactly where this bootstrap stopped reading, because `Read` on the raw
+* stream never buffers ahead of the count it was asked for.
+*/
+const STREAM_BOOTSTRAP = [
+	"$ErrorActionPreference='Continue'",
+	"[Console]::OutputEncoding=[Text.Encoding]::UTF8",
+	"$i=[Console]::OpenStandardInput()",
+	"$d=''",
+	"while($true){$b=$i.ReadByte();if($b -lt 0 -or $b -eq 10){break};if($b -ne 13){$d+=[char]$b}}",
+	"$n=[int]$d",
+	"$u=New-Object byte[] $n",
+	"$r=0",
+	"while($r -lt $n){$k=$i.Read($u,$r,$n-$r);if($k -le 0){break};$r+=$k}",
+	"$s=[Text.Encoding]::UTF8.GetString($u,0,$r)",
+	"$c=0",
+	"try{",
+	"  &([scriptblock]::Create($s))",
+	"}catch{",
+	"  [Console]::Error.WriteLine([string]($_|Out-String))",
+	"  $c=1",
+	"}",
+	"exit $c",
+	""
+].join("\r\n");
+/**
+* The constant powershell.exe command line for a streaming upload.
+*
+* The receiver travels on stdin right behind it, so this stays well clear of
+* cmd.exe's cap and does not change when the receiver does.
+*/
+function streamCommandLine() {
+	return "powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand " + encodeCommand(STREAM_BOOTSTRAP);
+}
+/**
 * The stdin payload for one command: the UTF-8 **byte** count, a newline, then
 * the raw script.
 *
@@ -226,11 +278,16 @@ function psListDir(dir) {
 		""
 	].join("\r\n");
 }
-/** Plain: remote file size in bytes (0 when missing). */
+/**
+* Plain: remote file size in bytes. Emits nothing at all when the path is
+* missing or is a directory, so the caller can tell "absent" from "empty" —
+* both used to collapse to the string "0", which made a download of a
+* nonexistent file look like a successful transfer of a zero-byte one.
+*/
 function psFileSize(p) {
 	return [
 		"$__f = Get-Item -LiteralPath " + sq(p) + " -ErrorAction SilentlyContinue",
-		"if ($null -eq $__f) { \"0\" } elseif ($__f.PSIsContainer) { \"0\" } else { [string]$__f.Length }",
+		"if ($null -ne $__f -and -not $__f.PSIsContainer) { [string]$__f.Length }",
 		""
 	].join("\r\n");
 }
@@ -265,6 +322,227 @@ function psWriteChunk(p, b64, append) {
 		""
 	].join("\r\n");
 }
+/** Magic stamped into the frame header that precedes every stream chunk. */
+const STREAM_FRAME_MAGIC = "DSHZ";
+/** Remote-side buffer used while draining stdin (or inflating a frame) into the file. */
+const STREAM_BUFFER_BYTES = 262144;
+/**
+* Wrap one payload in a stream frame: `DSHZ` + uint32LE length + mode + pad.
+*
+* The frame is what makes a compressed stream legal on a pipe. stdin cannot
+* seek, so the receiver has to be handed the exact byte count of the next gzip
+* member before it lets `GZipStream` touch it; otherwise the inflater would
+* read into the member that follows and the stream would desynchronize. The
+* mode byte travels with the payload so the client can switch between gzip and
+* raw per chunk.
+* @param payload - gzip member bytes or raw file bytes.
+* @param mode - `STREAM_FRAME_GZIP` or `STREAM_FRAME_RAW`.
+* @returns the framed chunk to place on the stdin stream.
+*/
+function buildStreamFrame(payload, mode) {
+	const frame = Buffer.alloc(10 + payload.length);
+	frame.write(STREAM_FRAME_MAGIC, 0, "ascii");
+	frame.writeUInt32LE(payload.length, 4);
+	frame[8] = mode;
+	frame[9] = 0;
+	payload.copy(frame, 10);
+	return frame;
+}
+/**
+* Streaming receiver: drain framed stdin chunks into the file named by the
+* header frame, until the declared byte count lands.
+*
+* This is the fast upload path. Instead of shipping base64 text inside a
+* PowerShell script — which costs one full shell create/command/delete cycle
+* per 48 KiB — the remote shell starts this script once and the client then
+* pushes bytes straight down the WinRS stdin stream. The only per-chunk cost
+* left is a single `Send`, so a whole file costs one shell and one command no
+* matter how large it is.
+*
+* The script deliberately takes **no arguments**. The destination path and
+* total byte count arrive as the first frame on stdin, which keeps the command
+* line a constant size: WinRS hands the command line to cmd.exe, whose limit
+* is about 8191 characters, and a long remote path interpolated into the
+* script would eat into that budget (the script is base64-of-UTF-16 on the
+* wire, so every character costs 2.67). Reading them from the stream removes
+* the limit entirely and mirrors how `powershellCommandLine` stays constant.
+*
+* Every wire chunk is a frame: `DSHZ` + 4-byte little-endian payload length +
+* 1 mode byte + 1 reserved, followed by exactly that many payload bytes. The
+* explicit frame is what makes a *pipe* usable for a compressed stream: stdin
+* cannot seek, so the receiver must be told how long the next gzip member is
+* before it hands the bytes to `GZipStream`, or the inflater would read into
+* the member that follows. The mode byte lets the client pick per chunk — gzip
+* when it actually shrinks the data, raw bytes when it would not — so
+* incompressible files never pay compression overhead.
+*
+* The script prints the three-line envelope on stdout with the byte count as
+* its payload, so the caller can prove the transfer landed complete.
+* @returns a PowerShell script suitable for `-EncodedCommand`.
+*/
+function psReceiveStream() {
+	return [
+		"$ErrorActionPreference = 'Stop'",
+		"$__a = ''",
+		"$__e = ''",
+		"$__c = 0",
+		"try {",
+		"  $__i = [Console]::OpenStandardInput()",
+		"  $__hdr = New-Object byte[] " + String(10),
+		"  $__got = 0",
+		"  while ($__got -lt $__hdr.Length) {",
+		"    $__k = $__i.Read($__hdr, $__got, $__hdr.Length - $__got)",
+		"    if ($__k -le 0) { break }",
+		"    $__got += $__k",
+		"  }",
+		"  if ($__got -lt $__hdr.Length) { throw " + sq("upload stream ended before its header") + " }",
+		"  if (-not ($__hdr[0] -eq 68 -and $__hdr[1] -eq 83 -and $__hdr[2] -eq 72 -and $__hdr[3] -eq 90)) { throw " + sq("upload stream lost frame alignment") + " }",
+		"  if ($__hdr[8] -ne " + String(2) + ") { throw " + sq("upload stream started without a header frame") + " }",
+		"  $__size = 0",
+		"  for ($__j = 0; $__j -lt 4; $__j++) { $__size = $__size -bor ([int]$__hdr[4 + $__j] -shl (8 * $__j)) }",
+		"  $__meta = New-Object byte[] $__size",
+		"  $__got = 0",
+		"  while ($__got -lt $__size) {",
+		"    $__k = $__i.Read($__meta, $__got, $__size - $__got)",
+		"    if ($__k -le 0) { break }",
+		"    $__got += $__k",
+		"  }",
+		"  if ($__got -lt $__size) { throw " + sq("upload stream truncated its header frame") + " }",
+		"  $__text = [System.Text.Encoding]::UTF8.GetString($__meta)",
+		"  $__cut = $__text.IndexOf([char]10)",
+		"  if ($__cut -lt 0) { throw " + sq("upload header frame is malformed") + " }",
+		"  $__n = [long]$__text.Substring(0, $__cut)",
+		"  $__p = $__text.Substring($__cut + 1)",
+		"  $__d = [System.IO.Path]::GetDirectoryName($__p)",
+		"  if (-not [string]::IsNullOrEmpty($__d)) { [System.IO.Directory]::CreateDirectory($__d) | Out-Null }",
+		"  $__fs = New-Object System.IO.FileStream($__p, [System.IO.FileMode]::Create, [System.IO.FileAccess]::Write, [System.IO.FileShare]::Read)",
+		"  $__w = 0",
+		"  try {",
+		"    $__buf = New-Object byte[] " + String(STREAM_BUFFER_BYTES),
+		"    while ($__w -lt $__n) {",
+		"      $__got = 0",
+		"      while ($__got -lt $__hdr.Length) {",
+		"        $__k = $__i.Read($__hdr, $__got, $__hdr.Length - $__got)",
+		"        if ($__k -le 0) { break }",
+		"        $__got += $__k",
+		"      }",
+		"      if ($__got -lt $__hdr.Length) { break }",
+		"      if (-not ($__hdr[0] -eq 68 -and $__hdr[1] -eq 83 -and $__hdr[2] -eq 72 -and $__hdr[3] -eq 90)) { throw " + sq("upload stream lost frame alignment") + " }",
+		"      $__size = 0",
+		"      for ($__j = 0; $__j -lt 4; $__j++) { $__size = $__size -bor ([int]$__hdr[4 + $__j] -shl (8 * $__j)) }",
+		"      $__mode = $__hdr[8]",
+		"      $__blob = New-Object byte[] $__size",
+		"      $__got = 0",
+		"      while ($__got -lt $__size) {",
+		"        $__k = $__i.Read($__blob, $__got, $__size - $__got)",
+		"        if ($__k -le 0) { break }",
+		"        $__got += $__k",
+		"      }",
+		"      if ($__got -lt $__size) { break }",
+		"      if ($__mode -eq " + String(1) + ") {",
+		"        $__ms = New-Object System.IO.MemoryStream(, $__blob)",
+		"        $__gz = New-Object System.IO.Compression.GZipStream($__ms, [System.IO.Compression.CompressionMode]::Decompress)",
+		"        try {",
+		"          while ($true) {",
+		"            $__k = $__gz.Read($__buf, 0, $__buf.Length)",
+		"            if ($__k -le 0) { break }",
+		"            $__fs.Write($__buf, 0, $__k)",
+		"            $__w += $__k",
+		"          }",
+		"        } finally { $__gz.Dispose(); $__ms.Dispose() }",
+		"      } else {",
+		"        $__fs.Write($__blob, 0, $__blob.Length)",
+		"        $__w += $__blob.Length",
+		"      }",
+		"    }",
+		"  } finally { $__fs.Dispose() }",
+		"  $__a = [string]$__w",
+		"} catch {",
+		"  $__a = [string]$__a + [string]($_.Exception.Message)",
+		"  $__c = 1",
+		"}",
+		sq(ENVELOPE_MARKER) + " + [string]$__c",
+		"'O:' + [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([string]$__a))",
+		"'E:' + [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([string]$__e))",
+		""
+	].join("\r\n");
+}
+/** Remote-side read buffer used by {@link psSendStream} while draining the file to stdout. */
+const SEND_BUFFER_BYTES = 262144;
+/**
+* Streaming sender: write one byte range of the file to standard output,
+* gzip-compressed, for the download path.
+*
+* This is the mirror of {@link psReceiveStream}. The old download path asked
+* for 48 KiB at a time, and every chunk cost a full shell create / command /
+* delete cycle — five HTTP round trips each — so a 2 MiB file took 129 s. Here
+* the shell is created once and the client then simply receives; the only
+* per-chunk cost left is one `Receive`, and the target streams the file as fast
+* as the transport will drain it.
+*
+* Two details make this work:
+*
+* - **Only stderr may carry text.** Anything written to the PowerShell success
+*   stream would be merged into the payload and corrupt the file, so the byte
+*   count and any error go to `[Console]::Error` and the exit code, not stdout.
+* - **The range is positional.** `Position` plus a byte count lets several
+*   shells serve different parts of one file concurrently; each writes to its
+*   own offset on the client, so completion order does not matter.
+*
+* Output is gzip-compressed unconditionally. Measured against this target, a
+* compressible 16 MiB file collapsed from 121 round trips to 1 (2.0 s), and an
+* incompressible 2 MiB file was no slower than raw (9457 ms vs 9582 ms), so the
+* compression pays for itself or costs nothing.
+* @param remotePath - file to read on the target.
+* @param start - first byte offset of this worker's range.
+* @param length - number of bytes this worker must send.
+* @returns a PowerShell script suitable for `-EncodedCommand`.
+*/
+function psSendStream(remotePath, start, length) {
+	return [
+		"$ErrorActionPreference = 'Stop'",
+		"$__o = [Console]::OpenStandardOutput()",
+		"$__n = 0",
+		"try {",
+		"  $__fs = [System.IO.File]::OpenRead(" + sq(remotePath) + ")",
+		"  try {",
+		"    $__fs.Position = [long]" + String(start),
+		"    $__left = [long]" + String(length),
+		"    $__gz = New-Object System.IO.Compression.GZipStream($__o, [System.IO.Compression.CompressionMode]::Compress, $true)",
+		"    try {",
+		"      $__buf = New-Object byte[] " + String(SEND_BUFFER_BYTES),
+		"      while ($__left -gt 0) {",
+		"        $__want = [int][Math]::Min([long]$__buf.Length, $__left)",
+		"        $__k = $__fs.Read($__buf, 0, $__want)",
+		"        if ($__k -le 0) { break }",
+		"        $__gz.Write($__buf, 0, $__k)",
+		"        $__n += $__k",
+		"        $__left -= $__k",
+		"      }",
+		"      $__gz.Flush()",
+		"    } finally { $__gz.Dispose() }",
+		"    $__o.Flush()",
+		"  } finally { $__fs.Dispose() }",
+		"  [Console]::Error.WriteLine('__DSH_DL__ OK ' + [string]$__n)",
+		"} catch {",
+		"  [Console]::Error.WriteLine('__DSH_DL__ ERR ' + [string]($_.Exception.Message))",
+		"  throw",
+		"}",
+		""
+	].join("\r\n");
+}
+/**
+* Wrap an arbitrary script in the constant powershell.exe invocation.
+*
+* Only safe for scripts that fit cmd.exe's ~8191 character command line (the
+* script is base64-of-UTF-16 on the wire, so it costs 2.67 characters each);
+* {@link psReceiveStream} outgrew that and travels on stdin instead.
+* @param script - the PowerShell script to run.
+* @returns the command line to hand to WinRS.
+*/
+function scriptCommandLine(script) {
+	return "powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand " + encodeCommand(script);
+}
 /** Decode one base64 envelope field, tolerating whitespace the transport added. */
 function decodeField(base64) {
 	return Buffer.from(base64.replace(/\s+/g, ""), "base64").toString("utf8");
@@ -316,6 +594,197 @@ function stripClixml(stderr) {
 	return stderr.replace(CLIXML_HEADER, "").replace(CLIXML_RECORDS, "").trim();
 }
 //#endregion
+//#region src/engine/wsman.ts
+/**
+* Raw WSMan `Send` for the streaming upload path.
+*
+* The bundled `winrm-client` can only put text on the WinRS stdin stream: its
+* `doSendInput` base64-encodes the input *again* on top of whatever the caller
+* already encoded, and it has no way to close the stream. Both are fatal for a
+* bulk transfer — double base64 costs 1.78x the bytes on the wire, and a
+* stdin stream that never ends cannot tell the remote receiver "that is all".
+*
+* This module therefore builds the `Send` envelope itself and posts it through
+* the library's own `sendHttp`, which keeps Basic/NTLM/SPNEGO and the HTTPS
+* options exactly as the rest of the transport uses them. The stream carries
+* raw file bytes, so the wire cost is 1.0x plus the envelope.
+*
+* The library is reached through `createRequire` rather than a static import
+* because `dist/src/utils/http.js` is an internal CommonJS path with no
+* `exports` map behind it. `loadSendHttp` returns null when that path is gone
+* (a future `winrm-client` layout change), which lets the caller fall back to
+* the old chunked path instead of failing the transfer.
+*/
+/**
+* Envelope ceiling declared on every Send, in bytes.
+*
+* This is what the *client* promises the server it will never exceed, and the
+* server enforces its own `MaxEnvelopeSizekb` on top. 512000 is the value the
+* target host reports, and it is far above the library's hardcoded 153600 —
+* raising it is what makes 256 KiB chunks legal.
+*/
+const WS_MAX_ENVELOPE_BYTES = 512e3;
+let sendHttpCache;
+/**
+* Resolve the library's `sendHttp`, or null when the internal path is absent.
+* @returns the send function, or null when it cannot be loaded.
+*/
+function loadSendHttp() {
+	if (sendHttpCache !== void 0) return sendHttpCache;
+	try {
+		const mod = createRequire(import.meta.url)("winrm-client/dist/src/utils/http.js");
+		sendHttpCache = typeof mod.sendHttp === "function" ? mod.sendHttp : null;
+	} catch {
+		sendHttpCache = null;
+	}
+	return sendHttpCache;
+}
+/**
+* Build one WSMan `Send` envelope carrying `chunk` on the stdin stream.
+*
+* The header mirrors what the library emits, with three deliberate changes:
+* `MaxEnvelopeSize` is raised to `limit`, the `Send` action replaces the
+* command's, and the stream body is the caller's base64 verbatim — no second
+* encode. `Name="stdin"` and `CommandId` are what bind the bytes to the
+* running receiver's standard input.
+* @param shellId - target shell from `Shell.doCreateShell`.
+* @param commandId - target command from `Command.doExecuteCommand`.
+* @param chunk - raw bytes to place on the remote stdin stream.
+* @param limit - envelope ceiling to declare.
+* @returns the SOAP envelope as a UTF-8 string.
+*/
+function buildSendEnvelope(shellId, commandId, chunk, limit) {
+	return "<?xml version=\"1.0\" encoding=\"UTF-8\"?><s:Envelope xmlns:s=\"http://www.w3.org/2003/05/soap-envelope\" xmlns:wsa=\"http://schemas.xmlsoap.org/ws/2004/08/addressing\" xmlns:wsman=\"http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd\" xmlns:p=\"http://schemas.microsoft.com/wbem/wsman/1/wsman.xsd\" xmlns:rsp=\"http://schemas.microsoft.com/wbem/wsman/1/windows/shell\"><s:Header><wsa:To>http://windows-host:5985/wsman</wsa:To><wsman:ResourceURI mustUnderstand=\"true\">http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd</wsman:ResourceURI><wsa:ReplyTo><wsa:Address mustUnderstand=\"true\">http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address></wsa:ReplyTo><wsman:MaxEnvelopeSize mustUnderstand=\"true\">" + String(limit) + "</wsman:MaxEnvelopeSize><wsa:MessageID>uuid:" + randomUUID() + "</wsa:MessageID><wsman:Locale mustUnderstand=\"false\" xml:lang=\"en-US\"/><wsman:OperationTimeout>PT60S</wsman:OperationTimeout><wsa:Action mustUnderstand=\"true\">http://schemas.microsoft.com/wbem/wsman/1/windows/shell/Send</wsa:Action><wsman:SelectorSet><wsman:Selector Name=\"ShellId\">" + shellId + "</wsman:Selector></wsman:SelectorSet></s:Header><s:Body><rsp:Send><rsp:Stream CommandId=\"" + commandId + "\" Name=\"stdin\">" + chunk.toString("base64") + "</rsp:Stream></rsp:Send></s:Body></s:Envelope>";
+}
+/**
+* Push one raw slice onto the remote stdin stream.
+*
+* A rejection here is safe to retry with a smaller slice: the server validates
+* the envelope size before dispatching it to the shell, so nothing reached the
+* receiver's stdin when the call fails on size.
+* @param target - connection parameters (auth already selected).
+* @param shellId - target shell.
+* @param commandId - target command.
+* @param chunk - raw bytes to send.
+* @param sendHttp - the resolved library function.
+* @param timeoutMs - per-request HTTP timeout.
+*/
+async function sendStdinChunk(target, shellId, commandId, chunk, sendHttp, timeoutMs) {
+	await sendHttp(buildSendEnvelope(shellId, commandId, chunk, WS_MAX_ENVELOPE_BYTES), target.host, target.port, target.path, target.username, target.password, target.authMethod, timeoutMs, target.useHttps, target.rejectUnauthorized);
+}
+/**
+* Whether a failed Send was refused for exceeding the envelope ceiling.
+*
+* WSMan reports this as a SOAP fault rather than a status code, and the exact
+* wording differs between the HTTP and HTTPS stacks, so the test looks for any
+* of the size-related phrasings plus the plain 413 status. It deliberately
+* does not match a bare "size" in unrelated text.
+* @param error - the rejection to classify.
+* @returns true when retrying with a smaller slice is the right response.
+*/
+function isEnvelopeTooLarge(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return /\b413\b/.test(message) || /envelope/i.test(message) || /MaxEnvelopeSize/i.test(message) || /maximum.*(size|length)/i.test(message);
+}
+/**
+* Build one WSMan `Receive` envelope asking for stdout and stderr.
+*
+* The library's own `buildReceiveOutputRequest` cannot be reused here because
+* it hardcodes `MaxEnvelopeSize` at 153600 in its shared header. Measured
+* against this target, that ceiling is what caps each response at 128 KiB —
+* raising it to 512000 lets one `Receive` return 128 KiB per stream, which is
+* the most the server will put in a single response regardless.
+* @param shellId - target shell.
+* @param commandId - target command whose streams are wanted.
+* @param limit - envelope ceiling to declare.
+* @returns the SOAP envelope as a UTF-8 string.
+*/
+function buildReceiveEnvelope(shellId, commandId, limit) {
+	return "<?xml version=\"1.0\" encoding=\"UTF-8\"?><s:Envelope xmlns:s=\"http://www.w3.org/2003/05/soap-envelope\" xmlns:wsa=\"http://schemas.xmlsoap.org/ws/2004/08/addressing\" xmlns:wsman=\"http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd\" xmlns:rsp=\"http://schemas.microsoft.com/wbem/wsman/1/windows/shell\"><s:Header><wsa:To>http://windows-host:5985/wsman</wsa:To><wsman:ResourceURI mustUnderstand=\"true\">http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd</wsman:ResourceURI><wsa:ReplyTo><wsa:Address mustUnderstand=\"true\">http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address></wsa:ReplyTo><wsman:MaxEnvelopeSize mustUnderstand=\"true\">" + String(limit) + "</wsman:MaxEnvelopeSize><wsa:MessageID>uuid:" + randomUUID() + "</wsa:MessageID><wsman:Locale mustUnderstand=\"false\" xml:lang=\"en-US\"/><wsman:OperationTimeout>PT60S</wsman:OperationTimeout><wsa:Action mustUnderstand=\"true\">http://schemas.microsoft.com/wbem/wsman/1/windows/shell/Receive</wsa:Action><wsman:SelectorSet><wsman:Selector Name=\"ShellId\">" + shellId + "</wsman:Selector></wsman:SelectorSet></s:Header><s:Body><rsp:Receive><rsp:DesiredStream CommandId=\"" + commandId + "\">stdout stderr</rsp:DesiredStream></rsp:Receive></s:Body></s:Envelope>";
+}
+/**
+* Decode a base64 text node that the XML parser may have coerced to a number.
+*
+* fast-xml-parser runs with `parseTagValue` enabled, so an all-digit text node
+* comes back as a JS number: `"0123"` parses to `123`, `"0000"` to `0`, and
+* `"1e55"` to a float. A base64 payload is usually long enough to contain a
+* non-digit and stay a string, but the final short chunk of a stream is exactly
+* where a leading zero can appear, and silently reinterpreting it would corrupt
+* the file. Converting through `String()` recovers the digits for every value
+* that lost only leading zeros; a value that came back in exponent form cannot
+* be recovered and is rejected rather than guessed at.
+* @param text - the raw text node as the parser produced it.
+* @returns the base64 text, or null when it cannot be reconstructed.
+*/
+function coerceBase64(text) {
+	if (typeof text === "string") return text.replace(/\s+/g, "");
+	if (typeof text === "number" && Number.isFinite(text) && Number.isInteger(text) && text >= 0) return String(text);
+	return null;
+}
+/**
+* Read the streams and exit code out of a Receive response.
+*
+* The library's `extractStreams` cannot be used for binary payloads: it decodes
+* every stream through `extractText`, which falls back to `String(obj)` for an
+* element that has attributes but no text node — turning the terminal
+* `End="true"` marker into the literal string `'[object Object]'` — and the
+* library's `doReceiveOutputNonBlocking` then `.trim()`s the decoded text,
+* which would eat whitespace bytes at either end of a real payload. This
+* reader keeps the distinction between "no text" (zero bytes) and "text" and
+* never trims.
+* @param response - the parsed XML object returned by `sendHttp`.
+* @returns the decoded streams and exit code.
+* @throws when a stream's text node cannot be decoded as base64.
+*/
+function readReceiveResult(response) {
+	const receive = ((response?.["s:Envelope"])?.["s:Body"])?.["rsp:ReceiveResponse"];
+	const streams = [];
+	if (receive !== void 0) {
+		const raw = receive["rsp:Stream"];
+		const list = raw === void 0 || raw === null ? [] : Array.isArray(raw) ? raw : [raw];
+		for (const element of list) {
+			const node = element;
+			const text = node !== null && typeof node === "object" && "_" in node ? node["_"] : "";
+			const attributes = node?.["$"] ?? {};
+			const name = String(attributes["@_Name"] ?? "");
+			const end = String(attributes["@_End"] ?? "") === "true";
+			if (text === "" || text === null || text === void 0) {
+				streams.push({
+					name,
+					data: Buffer.alloc(0),
+					end
+				});
+				continue;
+			}
+			const base64 = coerceBase64(text);
+			if (base64 === null) throw new Error("receive stream returned an undecodable text node: " + String(text));
+			streams.push({
+				name,
+				data: base64 === "" ? Buffer.alloc(0) : Buffer.from(base64, "base64"),
+				end
+			});
+		}
+	}
+	const rawExit = (receive?.["rsp:CommandState"])?.["rsp:ExitCode"];
+	const exitCode = rawExit === void 0 || rawExit === null ? void 0 : Number(rawExit);
+	return {
+		streams,
+		exitCode: exitCode !== void 0 && Number.isFinite(exitCode) ? exitCode : void 0
+	};
+}
+/**
+* Fetch one Receive response for a running command.
+* @param target - connection parameters (auth already selected).
+* @param shellId - target shell.
+* @param commandId - target command.
+* @param sendHttp - the resolved library function.
+* @param timeoutMs - per-request HTTP timeout.
+* @returns the decoded streams and exit code.
+*/
+async function receiveOutput(target, shellId, commandId, sendHttp, timeoutMs) {
+	return readReceiveResult(await sendHttp(buildReceiveEnvelope(shellId, commandId, WS_MAX_ENVELOPE_BYTES), target.host, target.port, target.path, target.username, target.password, target.authMethod, timeoutMs, target.useHttps, target.rejectUnauthorized));
+}
+//#endregion
 //#region src/engine/client.ts
 /**
 * WinRM transport bridge.
@@ -545,13 +1014,21 @@ async function testConnection(conn) {
 	}
 }
 const TRANSFER_CHUNK = 48 * 1024;
+/**
+* Size of a remote file, or null when the path does not exist or is a
+* directory. The distinction matters: a caller that treats "absent" as "empty"
+* writes an empty local file and reports success for a download that copied
+* nothing.
+*/
 async function remoteFileSize(conn, remotePath, timeoutMs = 6e4) {
-	const result = await runScript(conn, psFileSize(remotePath), { timeoutMs });
-	const value = Number.parseInt(result.stdout.trim(), 10);
-	return Number.isFinite(value) ? value : 0;
+	const text = (await runScript(conn, psFileSize(remotePath), { timeoutMs })).stdout.trim();
+	if (text === "") return null;
+	const value = Number.parseInt(text, 10);
+	return Number.isFinite(value) && value >= 0 ? value : null;
 }
 async function downloadChunks(conn, remotePath, onChunk, onProgress, timeoutMs = 6e4) {
 	const total = await remoteFileSize(conn, remotePath, timeoutMs);
+	if (total === null) throw new Error(`remote file not found: ${remotePath}`);
 	if (total === 0) return 0;
 	let offset = 0;
 	for (;;) {
@@ -577,16 +1054,355 @@ async function uploadBuffer(conn, remotePath, data, onProgress, timeoutMs = 6e4)
 	}
 	return written;
 }
+/** Raw slice size for the streaming path: 256 KiB, comfortably inside `MAX_SEND_SLICE_BYTES`. */
+const STREAM_CHUNK_BYTES = 262144;
+/**
+* Compress a slice only when it actually shrinks.
+*
+* Gzip on already-compressed input (zips, images, installers) produces output
+* marginally *larger* than its input, and the remote side then pays to inflate
+* it for nothing — measured at ~3.8x the wall time of sending the same bytes
+* raw. Local compression is cheap (~3.4 ms per 256 KiB even when it fails to
+* compress), so probing every slice costs almost nothing and the ratio is the
+* only thing that decides.
+*/
+const STREAM_GZIP_MIN_RATIO = .85;
+/** Per-Send HTTP budget; a single slice is small, so this only bounds a stalled connection. */
+const STREAM_SEND_TIMEOUT_MS = 12e4;
+/**
+* One streaming transfer over a single shell: create → run the receiver →
+* push the receiver script, the header frame and every data frame down stdin →
+* receive the envelope → delete the shell.
+*
+* The receiver script is the first thing on stdin because it does not fit the
+* command line (see `streamCommandLine`); the bootstrap in the command line
+* reads it and runs it in-process so it can keep reading the same stream.
+* @param conn - connection parameters.
+* @param remotePath - destination path on the target.
+* @param data - the file contents to send.
+* @param onProgress - called with cumulative bytes after each frame.
+* @param timeoutMs - whole-transfer budget.
+* @param authMethod - the auth scheme for this attempt.
+* @param sendHttp - the resolved library send function.
+* @returns the number of file bytes the receiver acknowledged writing.
+* @throws WinrmTimedOut when the deadline passes; other errors are transport failures.
+*/
+async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMethod, sendHttp) {
+	const base = baseParams(conn, authMethod);
+	const target = {
+		host: conn.host,
+		port: conn.port,
+		path: conn.path,
+		username: conn.username,
+		password: conn.password,
+		authMethod,
+		useHttps: conn.useHttps ?? false,
+		rejectUnauthorized: conn.rejectUnauthorized ?? true
+	};
+	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
+	const state = {
+		shellId: void 0,
+		timedOut: false,
+		settled: false
+	};
+	const total = data.length;
+	const inner = async () => {
+		const shellId = await Shell.doCreateShell(base);
+		state.shellId = shellId;
+		if (state.settled) {
+			Shell.doDeleteShell({
+				...base,
+				shellId
+			}).catch(() => void 0);
+			throw new WinrmTimedOut();
+		}
+		const commandId = await Command.doExecuteCommand({
+			...base,
+			shellId,
+			command: streamCommandLine()
+		});
+		await sendStdinChunk(target, shellId, commandId, Buffer.from(scriptPayload(psReceiveStream()), "utf8"), sendHttp, STREAM_SEND_TIMEOUT_MS);
+		const header = Buffer.from(String(total) + "\n" + remotePath, "utf8");
+		await sendStdinChunk(target, shellId, commandId, buildStreamFrame(header, 2), sendHttp, STREAM_SEND_TIMEOUT_MS);
+		let offset = 0;
+		let slice = STREAM_CHUNK_BYTES;
+		let ceiling = STREAM_CHUNK_BYTES;
+		while (offset < total) {
+			if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut();
+			const take = Math.min(slice, total - offset);
+			const chunk = data.subarray(offset, offset + take);
+			const gz = gzipSync(chunk, { level: 6 });
+			const compress = gz.length < chunk.length * STREAM_GZIP_MIN_RATIO;
+			const frame = buildStreamFrame(compress ? gz : chunk, compress ? 1 : 0);
+			try {
+				await sendStdinChunk(target, shellId, commandId, frame, sendHttp, STREAM_SEND_TIMEOUT_MS);
+			} catch (error) {
+				if (isEnvelopeTooLarge(error) && slice > 16384) {
+					slice = Math.max(16384, Math.floor(slice / 2));
+					ceiling = slice;
+					continue;
+				}
+				throw error;
+			}
+			offset += take;
+			onProgress?.(offset, total);
+			if (slice < ceiling) slice = Math.min(ceiling, slice * 2);
+		}
+		const receive = {
+			...base,
+			shellId,
+			commandId
+		};
+		const commandDeadline = Date.now() + timeoutMs;
+		let stdout = "";
+		let stderr = "";
+		for (;;) {
+			if (state.settled || Date.now() >= commandDeadline) throw new WinrmTimedOut();
+			const chunk = await Command.doReceiveOutputNonBlocking(receive);
+			stdout += chunk.output;
+			stderr += chunk.stderr;
+			if (chunk.isComplete) break;
+		}
+		const parsed = parseEnvelope(stdout);
+		if (parsed === null) throw new Error("streaming upload did not report completion: " + (stripClixml(stderr) || stdout).trim());
+		if (parsed.exitCode !== 0) throw new Error("streaming upload failed on the target: " + parsed.stdout.trim());
+		const written = Number.parseInt(parsed.stdout.trim(), 10);
+		if (!Number.isFinite(written) || written !== total) throw new Error(`streaming upload wrote ${parsed.stdout.trim()} of ${total} bytes`);
+		return written;
+	};
+	try {
+		return await raceDeadline(inner(), hardDeadline - Date.now());
+	} catch (error) {
+		if (error instanceof WinrmTimedOut || Date.now() >= hardDeadline) {
+			state.timedOut = true;
+			throw error instanceof WinrmTimedOut ? error : new WinrmTimedOut();
+		}
+		throw error;
+	} finally {
+		state.settled = true;
+		const shellId = state.shellId;
+		if (shellId !== void 0) {
+			const deletion = Shell.doDeleteShell({
+				...base,
+				shellId
+			}).catch(() => void 0);
+			if (state.timedOut);
+			else await Promise.race([deletion, sleep(DELETE_TIMEOUT_MS)]);
+		}
+	}
+}
+/**
+* Upload a buffer over a single WinRS stdin stream.
+*
+* This replaces the per-chunk shell cycle: one shell, one command and one
+* `Send` per 256 KiB, against a receiver that drains the stream straight into
+* the file. Measured at ~10 s for 2 MiB where the old path took 310 s.
+*
+* Returns null — rather than throwing — when the transport this path depends
+* on is unavailable (a future `winrm-client` layout that drops the internal
+* module it borrows), so the caller can fall back to {@link uploadBuffer}
+* instead of failing the transfer.
+* @param conn - connection parameters.
+* @param remotePath - destination path on the target.
+* @param data - the file contents to send.
+* @param onProgress - called with cumulative bytes after each frame.
+* @param timeoutMs - whole-transfer budget.
+* @returns bytes written, or null when the streaming path is unavailable.
+*/
+async function uploadStream(conn, remotePath, data, onProgress, timeoutMs = 6e5) {
+	const sendHttp = loadSendHttp();
+	if (sendHttp === null) return null;
+	const candidates = conn.useHttps ? ["basic", "ntlm"] : ["ntlm", "basic"];
+	let lastError;
+	for (const authMethod of candidates) try {
+		return await streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMethod, sendHttp);
+	} catch (error) {
+		if (error instanceof WinrmTimedOut) throw error;
+		lastError = error;
+	}
+	throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error("all WinRM authentication methods failed");
+}
+/** Smallest byte range worth giving a worker; below this the shell setup dominates. */
+const DOWNLOAD_MIN_RANGE_BYTES = 524288;
+/** Most shells to open for one download. Measured 3.9x on 16 MiB at four; more adds target load. */
+const DOWNLOAD_MAX_WORKERS = 4;
+/** Per-Receive HTTP timeout. The server long-polls, so this only bounds a stalled transport. */
+const DOWNLOAD_RECEIVE_TIMEOUT_MS = 12e4;
+/**
+* One worker's slice of a download: own shell, own command, own byte range.
+* @param conn - connection parameters.
+* @param remotePath - file being read.
+* @param start - first byte offset of this worker's range.
+* @param length - bytes this worker must deliver.
+* @param onData - receives each decompressed piece together with its file offset.
+* @param timeoutMs - budget for the whole range.
+* @param authMethod - the auth scheme for this attempt.
+* @param sendHttp - the resolved library HTTP function.
+* @returns the number of file bytes this worker delivered.
+*/
+async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeoutMs, authMethod, sendHttp) {
+	const base = baseParams(conn, authMethod);
+	const target = {
+		host: conn.host,
+		port: conn.port,
+		path: conn.path,
+		username: conn.username,
+		password: conn.password,
+		authMethod,
+		useHttps: conn.useHttps ?? false,
+		rejectUnauthorized: conn.rejectUnauthorized ?? true
+	};
+	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
+	const state = {
+		shellId: void 0,
+		timedOut: false,
+		settled: false
+	};
+	const inner = async () => {
+		const shellId = await Shell.doCreateShell(base);
+		state.shellId = shellId;
+		if (state.settled) {
+			Shell.doDeleteShell({
+				...base,
+				shellId
+			}).catch(() => void 0);
+			throw new WinrmTimedOut();
+		}
+		const commandId = await Command.doExecuteCommand({
+			...base,
+			shellId,
+			command: scriptCommandLine(psSendStream(remotePath, start, length))
+		});
+		const inflater = createGunzip();
+		let inflateError;
+		inflater.on("error", (error) => {
+			inflateError = error;
+		});
+		let written = 0;
+		let stderr = "";
+		inflater.on("data", (piece) => {
+			onData(start + written, piece);
+			written += piece.length;
+		});
+		let stdoutEnded = false;
+		let exitCode;
+		while (!stdoutEnded) {
+			if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut();
+			const result = await receiveOutput(target, shellId, commandId, sendHttp, DOWNLOAD_RECEIVE_TIMEOUT_MS);
+			let sawData = false;
+			for (const stream of result.streams) {
+				if (stream.data.length === 0) {
+					if (stream.name === "stdout" && stream.end) stdoutEnded = true;
+					continue;
+				}
+				sawData = true;
+				if (stream.name === "stdout") {
+					inflater.write(stream.data);
+					if (stream.end) stdoutEnded = true;
+				} else stderr += stream.data.toString("utf8");
+			}
+			if (inflateError !== void 0) throw inflateError;
+			if (result.exitCode !== void 0) exitCode = result.exitCode;
+			if (!sawData && exitCode !== void 0) break;
+		}
+		await new Promise((resolve, reject) => {
+			inflater.on("error", reject);
+			inflater.on("end", resolve);
+			inflater.end();
+		});
+		if (inflateError !== void 0) throw inflateError;
+		if (exitCode !== void 0 && exitCode !== 0) throw new Error("streaming download failed on the target: " + stderr.trim());
+		if (written !== length) throw new Error(`streaming download delivered ${written} of ${length} bytes`);
+		return written;
+	};
+	try {
+		return await raceDeadline(inner(), hardDeadline - Date.now());
+	} catch (error) {
+		state.timedOut = error instanceof WinrmTimedOut;
+		throw error;
+	} finally {
+		state.settled = true;
+		const shellId = state.shellId;
+		if (shellId !== void 0) try {
+			await raceDeadline(Shell.doDeleteShell({
+				...base,
+				shellId
+			}), DELETE_TIMEOUT_MS);
+		} catch {}
+	}
+}
+/**
+* Stream a remote file to a consumer, in parallel byte ranges.
+*
+* The old path asked for 48 KiB per shell lifecycle, so a 2 MiB file cost 43
+* round-trip cycles and 129 s. Measured against this target, one `Receive`
+* returns at most 128 KiB no matter how large an envelope is declared, which
+* makes a download latency-bound rather than bandwidth-bound; the fix is
+* therefore to run several ranges at once. Each worker opens its own shell and
+* streams its range gzip-compressed, and because ranges are absolute, the
+* caller can place each piece by offset and completion order does not matter.
+*
+* The remote side compresses unconditionally: a compressible 16 MiB file
+* arrives in one round trip (2.0 s), and an incompressible file was measured no
+* slower than raw (9457 ms vs 9582 ms).
+* @param conn - connection parameters.
+* @param remotePath - file to read.
+* @param onData - receives each decompressed piece with its absolute file offset.
+* @param onProgress - receives cumulative bytes delivered and the total size.
+* @param timeoutMs - budget for the whole download.
+* @returns the number of bytes delivered, or null when streaming is unavailable.
+*/
+async function downloadStream(conn, remotePath, onData, onProgress, timeoutMs = 6e5) {
+	const sendHttp = loadSendHttp();
+	if (sendHttp === null) return null;
+	const total = await remoteFileSize(conn, remotePath);
+	if (total === null) throw new Error(`remote file not found: ${remotePath}`);
+	if (total === 0) return 0;
+	const workers = Math.max(1, Math.min(DOWNLOAD_MAX_WORKERS, Math.ceil(total / DOWNLOAD_MIN_RANGE_BYTES)));
+	const rangeSize = Math.ceil(total / workers);
+	let transferred = 0;
+	let generation = 0;
+	let live = true;
+	const candidates = conn.useHttps ? ["basic", "ntlm"] : ["ntlm", "basic"];
+	let lastError;
+	try {
+		for (const authMethod of candidates) {
+			transferred = 0;
+			const mine = ++generation;
+			const report = (offset, data) => {
+				if (!live || mine !== generation) return;
+				onData(offset, data);
+				transferred += data.length;
+				onProgress?.(transferred, total);
+			};
+			try {
+				const ranges = [];
+				for (let start = 0; start < total; start += rangeSize) ranges.push({
+					start,
+					length: Math.min(rangeSize, total - start)
+				});
+				await Promise.all(ranges.map((range) => downloadWorkerOnce(conn, remotePath, range.start, range.length, report, timeoutMs, authMethod, sendHttp)));
+				return transferred;
+			} catch (error) {
+				if (error instanceof WinrmTimedOut) throw error;
+				lastError = error;
+			}
+		}
+		throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error("all WinRM authentication methods failed");
+	} finally {
+		live = false;
+	}
+}
 //#endregion
 //#region src/smb.ts
 /**
 * SMB transfer bridge.
 *
-* The WinRM base64 chunk bridge is reliable for small files but breaks for
-* large artifacts (the WinRM/HTTP envelope rejects large payloads), so whole
-* files ride the remote admin share. This module mounts the remote host's
-* admin share with `net use` (password passed via stdin, never argv), copies
-* whole files with node:fs, then verifies the SHA-256 on both ends.
+* SMB is the fast channel when the admin share is reachable, so `auto` tries it
+* first and falls back to the WinRM streaming path. This module mounts the
+* remote host's admin share with `net use` (password passed via stdin, never
+* argv), copies whole files with node:fs, then verifies the SHA-256 on both
+* ends.
 */
 /**
 * Convert a Windows drive path to its UNC admin-share form.
@@ -669,6 +1485,67 @@ async function remoteSha256(host, remotePath) {
 	if (match === null) throw new Error("SMB remote hash verification failed: " + stdout);
 	return match[1].toUpperCase();
 }
+/** How long a reachability verdict is trusted before probing again. */
+const SMB_PROBE_TTL_MS = 6e4;
+/** Budget for the TCP reachability probe; far below `net use`'s own timeout. */
+const SMB_PROBE_TIMEOUT_MS = 3e3;
+const smbProbeCache = /* @__PURE__ */ new Map();
+/**
+* Whether the target's SMB port (445) accepts a connection.
+*
+* `net use` is the only way to mount the admin share, but it has no useful
+* timeout: against a host whose 445 is filtered or whose SMB service is down it
+* spends a full minute before failing. That minute was being paid on *every*
+* `auto` upload before the WinRM fallback could even start — measured at 61 s
+* and 58 s on the test host, against a 12 s streaming transfer. A bare TCP
+* connect answers the same question in milliseconds.
+*
+* A negative verdict is cached briefly so a burst of transfers does not re-probe
+* for each one; a positive verdict is cached too, but the `net use` that follows
+* still reports its own failure if the share turns out to be unmountable.
+* @param host - target hostname or address.
+* @returns true when port 445 accepted a connection.
+*/
+async function smbReachable(host) {
+	const cached = smbProbeCache.get(host);
+	if (cached !== void 0 && Date.now() - cached.at < SMB_PROBE_TTL_MS) return cached.reachable;
+	const reachable = await new Promise((resolve) => {
+		const socket = createConnection({
+			host,
+			port: 445
+		});
+		let settled = false;
+		const finish = (value) => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			resolve(value);
+		};
+		const timer = setTimeout(() => finish(false), SMB_PROBE_TIMEOUT_MS);
+		socket.once("connect", () => {
+			clearTimeout(timer);
+			finish(true);
+		});
+		socket.once("error", () => {
+			clearTimeout(timer);
+			finish(false);
+		});
+		socket.once("timeout", () => {
+			clearTimeout(timer);
+			finish(false);
+		});
+		socket.setTimeout(SMB_PROBE_TIMEOUT_MS);
+	});
+	smbProbeCache.set(host, {
+		reachable,
+		at: Date.now()
+	});
+	return reachable;
+}
+/** Error thrown when SMB was requested or probed and the target is not listening. */
+function smbUnavailable(host) {
+	return /* @__PURE__ */ new Error("SMB is not reachable on " + host + ":445 (the admin share needs TCP 445 open and the Server service running)");
+}
 /**
 * Copy one local file to a remote Windows host over SMB, verifying the
 * remote SHA-256 matches the local source.
@@ -981,30 +1858,34 @@ var WinRmEngine = class {
 				total: data.length,
 				percent: 0
 			});
-			if (channel !== "winrm") try {
-				const outcome = await uploadSmb(entry, localPath, remotePath);
-				onProgress?.({
-					phase: "done",
-					file: remotePath,
-					transferred: outcome.bytes,
-					total: outcome.bytes,
-					percent: 100
-				});
-				return {
-					bytes: outcome.bytes,
-					channel: outcome.channel
-				};
-			} catch (error) {
-				if (channel === "smb") throw error;
-				onProgress?.({
-					phase: "connecting",
-					file: remotePath,
-					transferred: 0,
-					total: data.length,
-					percent: 0
-				});
+			if (channel !== "winrm") {
+				if (await smbReachable(entry.host)) try {
+					const outcome = await uploadSmb(entry, localPath, remotePath);
+					onProgress?.({
+						phase: "done",
+						file: remotePath,
+						transferred: outcome.bytes,
+						total: outcome.bytes,
+						percent: 100
+					});
+					return {
+						bytes: outcome.bytes,
+						channel: outcome.channel
+					};
+				} catch (error) {
+					if (channel === "smb") throw error;
+					onProgress?.({
+						phase: "connecting",
+						file: remotePath,
+						transferred: 0,
+						total: data.length,
+						percent: 0
+					});
+				}
+				else if (channel === "smb") throw smbUnavailable(entry.host);
 			}
-			const bytes = await uploadBuffer(connOf(entry), remotePath, data, (transferred, total) => {
+			const conn = connOf(entry);
+			const report = (transferred, total) => {
 				onProgress?.({
 					phase: "transferring",
 					file: remotePath,
@@ -1012,7 +1893,9 @@ var WinRmEngine = class {
 					total,
 					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0
 				});
-			});
+			};
+			let bytes = await uploadStream(conn, remotePath, data, report);
+			if (bytes === null) bytes = await uploadBuffer(conn, remotePath, data, report);
 			onProgress?.({
 				phase: "done",
 				file: remotePath,
@@ -1038,49 +1921,72 @@ var WinRmEngine = class {
 				total: 0,
 				percent: 0
 			});
-			if (channel !== "winrm") try {
-				const outcome = await downloadSmb(entry, remotePath, localPath);
-				onProgress?.({
-					phase: "done",
-					file: remotePath,
-					transferred: outcome.bytes,
-					total: outcome.bytes,
-					percent: 100
-				});
-				return {
-					bytes: outcome.bytes,
-					channel: outcome.channel
-				};
-			} catch (error) {
-				if (channel === "smb") throw error;
-				onProgress?.({
-					phase: "connecting",
-					file: remotePath,
-					transferred: 0,
-					total: 0,
-					percent: 0
-				});
+			if (channel !== "winrm") {
+				if (await smbReachable(entry.host)) try {
+					const outcome = await downloadSmb(entry, remotePath, localPath);
+					onProgress?.({
+						phase: "done",
+						file: remotePath,
+						transferred: outcome.bytes,
+						total: outcome.bytes,
+						percent: 100
+					});
+					return {
+						bytes: outcome.bytes,
+						channel: outcome.channel
+					};
+				} catch (error) {
+					if (channel === "smb") throw error;
+					onProgress?.({
+						phase: "connecting",
+						file: remotePath,
+						transferred: 0,
+						total: 0,
+						percent: 0
+					});
+				}
+				else if (channel === "smb") throw smbUnavailable(entry.host);
 			}
-			const { createWriteStream } = await import("node:fs");
-			const sink = createWriteStream(localPath, { mode: 384 });
+			const { open, rm } = await import("node:fs/promises");
+			let sink = null;
+			let completed = false;
 			let bytes = 0;
-			await new Promise((resolve, reject) => {
-				sink.on("error", reject);
-				downloadChunks(connOf(entry), remotePath, (b64) => {
-					const buffer = Buffer.from(b64, "base64");
-					bytes += buffer.length;
-					sink.write(buffer);
-				}, (transferred, total) => onProgress?.({
+			let queue = Promise.resolve();
+			const put = (offset, data) => {
+				bytes += data.length;
+				queue = queue.then(async () => {
+					if (sink === null) sink = await open(localPath, "w", 384);
+					await sink.write(data, 0, data.length, offset);
+				});
+				queue.catch(() => void 0);
+			};
+			const report = (transferred, total) => {
+				onProgress?.({
 					phase: "transferring",
 					file: remotePath,
 					transferred,
 					total,
 					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0
-				})).then(() => sink.end(resolve), (error) => {
-					sink.destroy();
-					reject(error);
 				});
-			});
+			};
+			try {
+				const conn = connOf(entry);
+				if (await downloadStream(conn, remotePath, put, report) === null) {
+					let offset = 0;
+					await downloadChunks(conn, remotePath, (b64) => {
+						const buffer = Buffer.from(b64, "base64");
+						put(offset, buffer);
+						offset += buffer.length;
+					}, report);
+				}
+				await queue;
+				if (sink === null) sink = await open(localPath, "w", 384);
+				completed = true;
+			} finally {
+				await queue.catch(() => void 0);
+				if (sink !== null) await sink.close();
+				if (!completed && sink !== null) await rm(localPath, { force: true }).catch(() => void 0);
+			}
 			onProgress?.({
 				phase: "done",
 				file: remotePath,
@@ -2265,7 +3171,7 @@ function winrmProcessTool(engine) {
 function winrmUploadTool(engine) {
 	return defineTool({
 		name: "winrm_upload",
-		description: "Upload a local file to a configured Windows host (SMB admin share preferred, base64 WinRM chunk fallback). The local path is on THIS machine (the dsh host). Triggers: upload file to Windows server, deploy artifact, copy config to Windows server.",
+		description: "Upload a local file to a configured Windows host. The bytes go over the SMB admin share when it is reachable, otherwise they are streamed over WinRM in one shell with per-chunk gzip (the 48 KiB base64 chunk path is kept only as a fallback). The local path is on THIS machine (the dsh host). Triggers: upload file to Windows server, deploy artifact, copy config to Windows server.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -2289,7 +3195,7 @@ function winrmUploadTool(engine) {
 					"smb",
 					"winrm"
 				],
-				description: "Transfer channel: smb (admin share), winrm (base64 chunks), or auto (default, SMB first with WinRM fallback)."
+				description: "Transfer channel: smb (admin share), winrm (streamed over the WinRS stdin channel), or auto (default, SMB first with WinRM fallback)."
 			}
 		},
 		output: {
@@ -2333,7 +3239,7 @@ function winrmUploadTool(engine) {
 function winrmDownloadTool(engine) {
 	return defineTool({
 		name: "winrm_download",
-		description: "Download a remote FILE from a configured Windows host to a local path on this machine (SMB admin share preferred, base64 WinRM chunk fallback). Directory download is not supported — download files individually. Triggers: download file from Windows server, fetch remote log/artifact.",
+		description: "Download a remote FILE from a configured Windows host to a local path on this machine. The bytes come over the SMB admin share when it is reachable, otherwise they are streamed over WinRM as parallel byte ranges (the 48 KiB base64 chunk path is kept only as a fallback). Directory download is not supported — download files individually. Triggers: download file from Windows server, fetch remote log/artifact.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -2357,7 +3263,7 @@ function winrmDownloadTool(engine) {
 					"smb",
 					"winrm"
 				],
-				description: "Transfer channel: smb (admin share), winrm (base64 chunks), or auto (default, SMB first with WinRM fallback)."
+				description: "Transfer channel: smb (admin share), winrm (streamed over parallel WinRS ranges), or auto (default, SMB first with WinRM fallback)."
 			}
 		},
 		output: {
@@ -2529,7 +3435,7 @@ const DEFAULT_ENABLED = true;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 151;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const WINRM_GUIDANCE = "本机已安装 dsh-winrm 插件（DSH 远程 Windows 运维，WinRM/PowerShell Remoting）：侧边栏「Windows」入口；仿照 dsh-ssh 插件开发。能力：主机配置存 ~/.dsh/dsh-winrm.json（GUI 配置后 agent 方可使用）；winrm_list 列出主机、winrm_exec 执行 PowerShell 命令（UTF-8 信封，中文不乱码）、winrm_service 服务管理（start/stop/restart/启动类型）、winrm_process 进程管理（list/kill）、winrm_upload/winrm_download 文件传输（base64 分块，无 SMB 依赖）、winrm_cluster 集群并发执行；Web 控制台走 WebSocket。认证：通过原生 Node.js WinRM 客户端（winrm-client）的 NTLM/Negotiate 与 Basic 实现，兼容本地账户与域账户；传输支持 http(5985)/https(5986)。前提：目标机需启用 WinRM（scripts/enable-winrm.ps1），本机无需 Python —— WinRM 走纯 Node 依赖。HTTP 仅建议受信内网使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出可能含敏感信息；传输/执行消耗真实远程资源，先确认再操作。用户提到「Windows 服务器 / WinRM / PowerShell 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
+const WINRM_GUIDANCE = "本机已安装 dsh-winrm 插件（DSH 远程 Windows 运维，WinRM/PowerShell Remoting）：侧边栏「Windows」入口；仿照 dsh-ssh 插件开发。能力：主机配置存 ~/.dsh/dsh-winrm.json（GUI 配置后 agent 方可使用）；winrm_list 列出主机、winrm_exec 执行 PowerShell 命令（UTF-8 信封，中文不乱码）、winrm_service 服务管理（start/stop/restart/启动类型）、winrm_process 进程管理（list/kill）、winrm_upload/winrm_download 文件传输（SMB 管理共享可达时优先，否则走 WinRM 流式传输，无 SMB 依赖，大文件经 SHA256 校验）、winrm_cluster 集群并发执行；Web 控制台走 WebSocket。认证：通过原生 Node.js WinRM 客户端（winrm-client）的 NTLM/Negotiate 与 Basic 实现，兼容本地账户与域账户；传输支持 http(5985)/https(5986)。前提：目标机需启用 WinRM（scripts/enable-winrm.ps1），本机无需 Python —— WinRM 走纯 Node 依赖。HTTP 仅建议受信内网使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出可能含敏感信息；传输/执行消耗真实远程资源，先确认再操作。用户提到「Windows 服务器 / WinRM / PowerShell 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
 /**
 * Mount the WinRM engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.