dsh-winrm 0.1.1 → 0.3.0

package/lib/index.js

@@ -1,14 +1,61 @@
+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";
 import { WebSocket, WebSocketServer } from "ws";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/powershell.ts
+/**
+* PowerShell snippet builders and the WinRM UTF-8 envelope.
+*
+* The user script is delivered on the WinRS **stdin** stream, not on the
+* command line. WinRS hands the command line to cmd.exe, which caps it at
+* ~8191 characters; `-EncodedCommand` inflates a script by 2.67x
+* (UTF-16LE → base64), so the command line can carry only about 1.5 KB of
+* script. That silently broke every large payload — most visibly the 48 KiB
+* transfer chunk, whose embedded base64 alone is ~65K characters.
+*
+* So the command line is now a *constant* outer script and the user script
+* rides stdin, which has no such limit (verified to 200 KB).
+*
+* The outer script reads a byte count, then that many bytes, starts a child
+* `powershell.exe` and feeds it the script on its stdin. The process boundary
+* is what makes `exit N` and an uncaught `throw` survivable: they terminate
+* the *child*, and the outer script is still alive to print the envelope.
+* `-EncodedCommand` for the child also sidesteps the execution policy
+* entirely — the policy governs `.ps1` files, not encoded commands — so no
+* temp file is written and no policy block can lose the envelope.
+*
+* The child body is `& (...) 2>&1 | Out-String -Stream`. Both halves matter:
+* `2>&1` pulls error records into the success stream, `Out-String -Stream`
+* stringifies them onto stdout *line by line*. Plain `Out-String` would also
+* stringify them but buffers the whole pipeline, discarding everything
+* produced before a mid-script `exit`; bare `2>&1` without `Out-String`
+* leaves the records to be re-serialized as CLIXML on stderr, where the
+* envelope's CLIXML stripping deletes the text outright.
+*
+* The envelope is three lines — a marker with the exit code, then one base64
+* line per stream:
+*
+*     __DSH_WINRM__<code>
+*     O:<base64 of UTF-8 stdout>
+*     E:<base64 of UTF-8 stderr>
+*
+* Every payload is ASCII, so the transport cannot corrupt it and Chinese
+* output survives losslessly. The `O:` / `E:` labels are load-bearing: the
+* WinRM client trims each response chunk, which can eat the newline between
+* two lines, and base64 never contains `:`, so the labels stay parseable
+* even when the separators vanish.
+*/
+/** Marker line prefix carrying the exit code: '__DSH_WINRM__<code>'. */
+const ENVELOPE_MARKER = "__DSH_WINRM__";
 /** PS single-quoted literal (doubles embedded quotes). */
 function sq(value) {
 	return "'" + value.replace(/'/g, "''") + "'";
@@ -18,28 +65,170 @@ function encodeCommand(script) {
 	return Buffer.from(script, "utf16le").toString("base64");
 }
 /**
-* The UTF-8 WinRM session script: runs `userScript` inside a script block,
-* merges stderr, prints the exit-code marker and base64 of UTF-8 output.
+* Outer script (constant, so the command line never grows with the payload):
+* read `<byteCount>\n<utf8 script>` from stdin, run it in a child
+* powershell.exe, then print the three-line envelope.
+*
+* The child is started with redirected streams *before* anything is written to
+* its stdin, and both readers are started before the write, so a child that
+* fills a pipe buffer cannot deadlock the outer script. Closing the writer is
+* what gives the child a real EOF — without it the child would block forever
+* on `CopyTo`.
 */
-function wrapEnvelope(userScript) {
-	return [
-		"$ErrorActionPreference = 'Continue'",
-		"$__out = & { " + userScript + " } 2>&1 | Out-String -Width 4096",
-		"$__code = 0",
-		"if ($null -ne $LASTEXITCODE) { $__code = $LASTEXITCODE }",
-		"[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
-		"'__DSH_WINRM__' + [string]$__code",
-		"[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([string]$__out))",
+const OUTER_SCRIPT = [
+	"$ErrorActionPreference='Continue'",
+	"$z=@'",
+	[
+		"$ErrorActionPreference='Continue'",
+		"[Console]::OutputEncoding=[Text.Encoding]::UTF8",
+		"$i=[Console]::OpenStandardInput()",
+		"$m=New-Object System.IO.MemoryStream",
+		"$i.CopyTo($m)",
+		"$s=[Text.Encoding]::UTF8.GetString($m.ToArray())",
+		"if($s.Length -gt 0 -and [int]$s[0] -eq 0xFEFF){$s=$s.Substring(1)}",
+		"$c=0",
+		"try{ &([scriptblock]::Create($s)) 2>&1 | Out-String -Stream -Width 4096",
+		"if($null -ne $LASTEXITCODE){$c=$LASTEXITCODE}",
+		"}catch{ $_|Out-String; $c=1 }",
+		"exit $c",
 		""
-	].join("\r\n");
+	].join("\r\n"),
+	"'@",
+	"$a=''",
+	"$e=''",
+	"$c=0",
+	"try{",
+	"  $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)",
+	"  $p=New-Object System.Diagnostics.ProcessStartInfo",
+	"  $p.FileName='powershell.exe'",
+	"  $p.UseShellExecute=$false",
+	"  $p.RedirectStandardOutput=$true",
+	"  $p.RedirectStandardError=$true",
+	"  $p.RedirectStandardInput=$true",
+	"  $p.StandardOutputEncoding=[Text.Encoding]::UTF8",
+	"  $p.StandardErrorEncoding=[Text.Encoding]::UTF8",
+	"  $p.CreateNoWindow=$true",
+	"  $p.Arguments='-NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand '+[Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($z))",
+	"  $q=[System.Diagnostics.Process]::Start($p)",
+	"  $x=$q.StandardOutput.ReadToEndAsync()",
+	"  $y=$q.StandardError.ReadToEndAsync()",
+	"  $w=New-Object System.IO.StreamWriter($q.StandardInput.BaseStream,(New-Object System.Text.UTF8Encoding($false)))",
+	"  $w.Write($s)",
+	"  $w.Flush()",
+	"  $w.Close()",
+	"  $q.WaitForExit()",
+	"  $a=[string]$x.Result",
+	"  $e=[string]$y.Result",
+	"  $c=$q.ExitCode",
+	"}catch{",
+	"  $a=[string]$a+[string]($_|Out-String)",
+	"  $c=1",
+	"}",
+	sq(ENVELOPE_MARKER) + "+[string]$c",
+	"'O:'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$a))",
+	"'E:'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$e))",
+	""
+].join("\r\n");
+/**
+* The constant powershell.exe command line that runs the envelope.
+*
+* Deliberately takes no payload: keeping the command line under cmd.exe's
+* ~8191-character cap is the whole point of the stdin channel.
+*/
+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);
 }
-/** One-shot script body for the PowerShell session already created by WinRM. */
-function winrmPowerShellScript(userScript) {
-	return wrapEnvelope(userScript);
+/**
+* The stdin payload for one command: the UTF-8 **byte** count, a newline, then
+* the raw script.
+*
+* The count is in bytes, not characters, because the outer script sizes its
+* receive buffer from it — a script with multi-byte characters would otherwise
+* be truncated mid-character.
+* @param userScript - the PowerShell script to run.
+* @returns the payload to send on WinRS stdin.
+*/
+function scriptPayload(userScript) {
+	return String(Buffer.byteLength(userScript, "utf8")) + "\n" + userScript;
 }
-/** The full powershell.exe command line (ASCII-safe) for a script body. */
-function powershellCommandLine(script) {
-	return "powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand " + encodeCommand(script);
+/**
+* Split a payload into Send-sized pieces without cutting a surrogate pair.
+*
+* `Command.doSendInput` encodes each piece to UTF-8 independently, so a lone
+* surrogate at a chunk boundary would be replaced with U+FFFD and corrupt the
+* script. Iterating with `for…of` yields whole code points, so a pair always
+* stays in one piece.
+* @param payload - the full stdin payload.
+* @returns the pieces to send in order; never empty.
+*/
+function splitScriptPayload(payload) {
+	const pieces = [];
+	let piece = "";
+	for (const ch of payload) {
+		if (piece.length + ch.length > 16384) {
+			pieces.push(piece);
+			piece = "";
+		}
+		piece += ch;
+	}
+	if (piece !== "" || pieces.length === 0) pieces.push(piece);
+	return pieces;
 }
 /** JSON: full service table (CIM). */
 function psListServices() {
@@ -89,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");
 }
@@ -128,38 +322,260 @@ 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;
 /**
-* Parse the envelope output: { exitCode, text } or null when absent.
+* Wrap one payload in a stream frame: `DSHZ` + uint32LE length + mode + pad.
 *
-* The base64 body is optional and the separating newline may be missing: a
-* command that printed nothing emits the marker alone (an empty string has
-* no base64 body), and a transport that trims each response drops the
-* trailing newline. The exit code is signed because `$LASTEXITCODE` can be
-* negative.
+* 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");
+}
+/**
+* Parse the three-line envelope: { exitCode, stdout, stderr } or null when absent.
+*
+* Fields are located by their `O:` / `E:` labels rather than by splitting on
+* newlines, because the WinRM client trims every response chunk and can drop
+* the newline that separated two lines. base64's alphabet has no colon, so a
+* label can only ever be a delimiter and the search cannot land on payload
+* data. The exit code is signed because `$LASTEXITCODE` can be negative.
+* @param output - the raw stdout accumulated from the WinRS stdout stream.
+* @returns the decoded envelope, or null when the marker is missing.
 */
 function parseEnvelope(output) {
-	const match = /^__DSH_WINRM__(-?\d+)(?:\r?\n([\s\S]*))?$/.exec(output);
-	if (match === null) return null;
-	const exitCode = Number.parseInt(match[1], 10);
-	const payload = (match[2] ?? "").trim();
-	try {
-		return {
-			exitCode,
-			text: Buffer.from(payload, "base64").toString("utf8")
-		};
-	} catch {
-		return {
-			exitCode,
-			text: payload
-		};
-	}
+	const text = output.trim();
+	const head = (/* @__PURE__ */ new RegExp("^__DSH_WINRM__(-?\\d+)")).exec(text);
+	if (head === null) return null;
+	const stdoutAt = text.indexOf("O:");
+	const stderrAt = stdoutAt === -1 ? -1 : text.indexOf("E:", stdoutAt + 2);
+	return {
+		exitCode: Number.parseInt(head[1], 10),
+		stdout: stdoutAt === -1 ? "" : decodeField(text.slice(stdoutAt + 2, stderrAt === -1 ? void 0 : stderrAt)),
+		stderr: stderrAt === -1 ? "" : decodeField(text.slice(stderrAt + 2))
+	};
 }
 /** The `#< CLIXML` stream header PowerShell writes once before its serialized records. */
 const CLIXML_HEADER = /^#< CLIXML\r?$/gm;
 /** One serialized record block (`<Objs …>…</Objs>`) holding host progress/verbose records. */
 const CLIXML_RECORDS = /<Objs\b[^>]*>[\s\S]*?<\/Objs>\r?\n?/g;
 /**
-* Remove PowerShell's CLIXML host records from the WinRS stderr stream.
+* Remove PowerShell's CLIXML host records from a stderr stream.
 *
 * PowerShell marks its stderr stream with a `#< CLIXML` header line and
 * serializes the remote host's own progress/verbose records into `<Objs>`
@@ -168,25 +584,217 @@ const CLIXML_RECORDS = /<Objs\b[^>]*>[\s\S]*?<\/Objs>\r?\n?/g;
 * header and a record block (for example `[Console]::Error`) is real output,
 * not part of the CLIXML payload.
 *
-* The script's own error output is already merged into stdout by the
-* envelope, so this only removes transport-level noise.
-* @param stderr - raw stderr text captured from the WinRS stream.
+* The script's own PowerShell errors are already stringified into the
+* envelope's stdout by `Out-String -Stream`, so this only removes
+* transport-level noise such as module-load progress.
+* @param stderr - raw stderr text captured from the WinRS stream or the envelope.
 * @returns the stderr text without CLIXML host records.
 */
 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.
 *
 * Runs each PowerShell payload over a native Node.js WinRM client
-* (winrm-client) — no Python/pywinrm subprocess. The script rides the
-* UTF-8 base64 envelope (marker + base64 of UTF-8 output) so Chinese and
-* any codepage output survives the WinRM transport losslessly; the envelope
-* is base64-encoded with `-EncodedCommand`, keeping the command line a
-* single ASCII-safe line that WinRS/cmd.exe cannot mangle.
+* (winrm-client) — no Python/pywinrm subprocess. The script is delivered on
+* the WinRS **stdin** stream and answers on the UTF-8 base64 envelope, so
+* Chinese and any codepage output survives the transport losslessly and the
+* command line stays a constant, ASCII-safe line that WinRS/cmd.exe cannot
+* mangle. See powershell.ts for why the command line cannot carry the script.
 *
 * Auth is chosen per attempt (HTTPS: Basic first, then NTLM; HTTP: NTLM
 * first, then Basic) with fallback, so a host that only enables one scheme
@@ -245,17 +853,17 @@ function baseParams(conn, authMethod) {
 	};
 }
 /**
-* One shell lifecycle: create → run the encoded script → receive until the
-* command completes → delete. Bounded by an overall deadline; on timeout the
-* delete is fired without blocking the caller.
+* One shell lifecycle: create → run the constant envelope script → push the
+* payload on stdin → receive until the command completes → delete. Bounded by
+* an overall deadline; on timeout the delete is fired without blocking.
 * @param conn - connection parameters.
-* @param envelope - the wrapped UTF-8 envelope script (already prepared).
+* @param payload - the stdin payload (`<byteCount>\n<script>`).
 * @param timeoutMs - command execution budget measured from just after Execute.
 * @param authMethod - the auth scheme for this attempt.
 * @returns stdout/stderr captured from the WinRS streams.
 * @throws WinrmTimedOut when the deadline passes; other errors are auth/transport failures.
 */
-async function attemptOnce(conn, envelope, timeoutMs, authMethod) {
+async function attemptOnce(conn, payload, timeoutMs, authMethod) {
 	const base = baseParams(conn, authMethod);
 	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
 	const state = {
@@ -273,11 +881,16 @@ async function attemptOnce(conn, envelope, timeoutMs, authMethod) {
 			}).catch(() => void 0);
 			throw new WinrmTimedOut();
 		}
-		const command = powershellCommandLine(envelope);
 		const commandId = await Command.doExecuteCommand({
 			...base,
 			shellId,
-			command
+			command: powershellCommandLine()
+		});
+		for (const piece of splitScriptPayload(payload)) await Command.doSendInput({
+			...base,
+			shellId,
+			commandId,
+			input: piece
 		});
 		const receive = {
 			...base,
@@ -324,16 +937,16 @@ async function attemptOnce(conn, envelope, timeoutMs, authMethod) {
 * succeeds. A timeout aborts immediately (retrying auth would waste the
 * remaining budget on a reachable-but-slow host).
 * @param conn - connection parameters.
-* @param envelope - the wrapped UTF-8 envelope script.
+* @param payload - the stdin payload (`<byteCount>\n<script>`).
 * @param timeoutMs - command execution budget.
 * @returns captured stdout/stderr.
 * @throws WinrmTimedOut on deadline; the last auth/transport error when every scheme fails.
 */
-async function runWinrm(conn, envelope, timeoutMs) {
+async function runWinrm(conn, payload, timeoutMs) {
 	const candidates = conn.useHttps ? ["basic", "ntlm"] : ["ntlm", "basic"];
 	let lastError;
 	for (const authMethod of candidates) try {
-		return await attemptOnce(conn, envelope, timeoutMs, authMethod);
+		return await attemptOnce(conn, payload, timeoutMs, authMethod);
 	} catch (error) {
 		if (error instanceof WinrmTimedOut) throw error;
 		lastError = error;
@@ -343,10 +956,10 @@ async function runWinrm(conn, envelope, timeoutMs) {
 async function runScript(conn, script, options = {}) {
 	const started = Date.now();
 	const timeoutMs = options.timeoutMs ?? 6e4;
-	const envelope = winrmPowerShellScript(script);
+	const payload = scriptPayload(script);
 	let outcome;
 	try {
-		outcome = await runWinrm(conn, envelope, timeoutMs);
+		outcome = await runWinrm(conn, payload, timeoutMs);
 	} catch (error) {
 		if (error instanceof WinrmTimedOut) return {
 			stdout: "",
@@ -360,13 +973,13 @@ async function runScript(conn, script, options = {}) {
 	const raw = outcome.stdout;
 	const parsed = parseEnvelope(raw);
 	const exitCode = parsed !== null ? parsed.exitCode : 1;
-	const stderr = parsed !== null ? stripClixml(outcome.stderr) : outcome.stderr;
+	const stderr = parsed !== null ? stripClixml(parsed.stderr) : outcome.stderr;
 	options.onChunk?.({
 		output: raw,
 		stderr
 	});
 	return {
-		stdout: parsed !== null ? parsed.text : raw,
+		stdout: parsed !== null ? parsed.stdout : raw,
 		stderr,
 		exitCode,
 		timedOut: false,
@@ -401,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 (;;) {
@@ -433,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.
@@ -525,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.
@@ -837,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,
@@ -868,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,
@@ -894,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,
@@ -2145,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: {
@@ -2213,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: {