dsh-winrm 0.4.0 → 0.4.1

package/README.en.md

@@ -123,8 +123,10 @@ Transport relies on the native Node.js [winrm-client](https://github.com/shide19
 - The console is a command session: it does not preserve PowerShell variables or the current directory, and every command runs independently
 - Uploads go over **one stdin stream**: a single shell, a single command, one `Send` per 256 KB, with per-chunk gzip for compressible content (a 1.7 MB JSON fixture travels as 91 KB on the wire). The old 48 KB chunked path is kept as a fallback, used only when the streaming channel is unavailable
 - Downloads go over **parallel byte ranges**: up to four workers by default, each with its own shell reading an absolute byte range of the same file, compressed on the remote side and written locally at the matching offset (measured: 2 MiB in about 10-12 s, 16 MiB in about 21-23 s, 16 MiB of compressible content in about 6 s; the old 48 KB chunked path needed 129 s for 2 MiB and remains as a fallback). A single server `Receive` returns at most 128 KB regardless of the envelope size, so downloads are round-trip bound rather than bandwidth bound
-- `channel=auto` (the default) probes port 445 first: `net use` has no short timeout of its own and takes about 60 s to fail when SMB is unavailable, and that wait used to happen before every upload. It is now decided within 3 s and the transfer goes straight over WinRM
+- `channel=auto` (the default) probes port 445 first: `net use` has no short timeout of its own and takes about 60 s to fail when SMB is unavailable, and that wait used to happen before every upload. It is now decided within 3 s and the transfer goes straight over WinRM. An explicit `channel=smb` on a host whose 445 is closed fails immediately and names `winrm` as the way out
+- A streaming transfer is bounded by **whether bytes are still moving**, not by a fixed deadline for the whole transfer: it keeps going as long as data arrives, and only a range that delivers nothing for 180 s is treated as stalled. A 700 MiB file therefore completes normally at the ~0.73 MiB/s this link measures even though it takes about sixteen minutes; the absolute cap exists only so a wedged transfer cannot stay alive forever, and it scales with the payload
 - A failed download leaves no residue: bytes already written are discarded and the target file is removed. If the failure happens before any byte arrives (missing path, target is a directory, host unreachable), an existing local file is left untouched — the target file is only created on the first write
+- When an attempt is abandoned mid-transfer (for example a failed auth candidate retried from the start), the sender process on the target can outlive it and keep the file open until its shell is reclaimed; a transfer that finishes normally exits on its own. If a remote file refuses to delete, end the corresponding `powershell.exe` sender on the target first
 - A single command times out after 60 s by default; pass `timeoutMs` to change it
 - The target machine must already have WinRM enabled (see above); cleartext HTTP Basic must not be used on the public internet
 - Closing and reopening the panel returns to the Hosts tab: the panel occupies the `main` slot, so it unmounts when you switch back to the conversation and the active tab is not preserved across toggles

package/README.md

@@ -123,8 +123,10 @@ scripts/
 - 控制台是命令会话，不保持 PowerShell 变量和当前目录状态；每条命令独立执行
 - 上传走**单条 stdin 流**：一个 shell、一个命令，每 256KB 一个 `Send`，可压缩内容自动按块 gzip（实测 1.7MB JSON 线上仅 91KB）。旧的 48KB 分块路径保留为回退，仅在流式通道不可用时启用
 - 下载走**并行区间流**：默认最多 4 个 worker，各自一个 shell 读同一文件的绝对字节区间，远端 gzip 后回传，本地按 offset 落位（实测 2MiB 约 10-12 秒，16MiB 约 21-23 秒，可压缩的 16MiB 约 6 秒；旧的 48KB 分块路径 2MiB 需 129 秒，保留为回退）。服务端单次 `Receive` 最多回 128KB，与信封大小无关，所以下载是往返次数受限而非带宽受限
-- `channel=auto`（默认）先探测目标机 445 端口：`net use` 自身没有短超时，SMB 不可用时要等约 60 秒才失败，此前这段等待发生在每次上传之前。现在 3 秒内判定并直接走 WinRM
-- 下载失败不留残file：已写入的数据会被丢弃、目标文件被删除；若失败发生在任何字节到达之前（路径不存在、目标是目录、主机不可达），已存在的本地文件保持原样不动（目标文件在首次写入时才创建）
+- `channel=auto`（默认）先探测目标机 445 端口：`net use` 自身没有短超时，SMB 不可用时要等约 60 秒才失败，此前这段等待发生在每次上传之前。现在 3 秒内判定并直接走 WinRM；显式 `channel=smb` 且 445 未开放时立即报错，并提示改用 `winrm`
+- 流式传输以**字节是否还在流动**判定超时，而不是给整次传输一个固定时限：只要还有数据到达就继续，某条区间连续 180 秒没有任何字节才判失败。因此大文件（实测 700MiB）在该链路的约 0.73MiB/s 速率下会跑十几分钟并正常完成；绝对上限只是防止传输卡死后永久占用，按载荷大小放大
+- 下载失败不留残留文件：已写入的数据会被丢弃、目标文件被删除；若失败发生在任何字节到达之前（路径不存在、目标是目录、主机不可达），已存在的本地文件保持原样不动（目标文件在首次写入时才创建）
+- 一次传输被中途放弃时（例如某次认证尝试失败后从头重试），目标机上的发送进程可能残留并继续占用该文件，直到其 shell 被回收；正常结束的传输会自行退出。遇到远端文件删不掉时，先结束目标机上对应的 `powershell.exe` 发送进程再删
 - 单命令默认 60s 超时，可传 `timeoutMs`
 - 目标机需已启用 WinRM（见上）；HTTP 明文 Basic 不应用于公网
 - 面板关闭再打开会回到「主机」页签：面板是 `main` 插槽的占用者，切回对话时卸载，页签状态不跨开关保留

package/lib/client.js

@@ -707,17 +707,17 @@ if (typeof document !== "undefined" && document.querySelector("style[data-plugin
 	document.head.appendChild(tag);
 }
 var cards_module_css_default = {
+	"diffStat": "X_s05W_diffStat",
 	"rowError": "X_s05W_rowError",
-	"sep": "X_s05W_sep",
-	"removed": "X_s05W_removed",
-	"meta": "X_s05W_meta",
-	"summary": "X_s05W_summary",
 	"detail": "X_s05W_detail",
-	"wrap": "X_s05W_wrap",
 	"added": "X_s05W_added",
-	"diffStat": "X_s05W_diffStat",
-	"title": "X_s05W_title",
-	"note": "X_s05W_note"
+	"note": "X_s05W_note",
+	"removed": "X_s05W_removed",
+	"wrap": "X_s05W_wrap",
+	"summary": "X_s05W_summary",
+	"sep": "X_s05W_sep",
+	"meta": "X_s05W_meta",
+	"title": "X_s05W_title"
 };
 //#endregion
 //#region src/client/tool/cards.tsx
@@ -1080,93 +1080,93 @@ if (typeof document !== "undefined" && document.querySelector("style[data-plugin
 	document.head.appendChild(tag);
 }
 var panel_module_css_default = {
-	"groupToggle": "hAbY3W_groupToggle",
-	"dirSize": "hAbY3W_dirSize",
-	"tunnelRow": "hAbY3W_tunnelRow",
-	"actions": "hAbY3W_actions",
-	"primaryButton": "hAbY3W_primaryButton",
-	"search": "hAbY3W_search",
-	"cellPre": "hAbY3W_cellPre",
-	"consoleOutput": "hAbY3W_consoleOutput",
-	"controls": "hAbY3W_controls",
-	"utf8Note": "hAbY3W_utf8Note",
-	"formCard": "hAbY3W_formCard",
-	"inlineTest": "hAbY3W_inlineTest",
-	"iconButton": "hAbY3W_iconButton",
-	"loading": "hAbY3W_loading",
-	"browsePanel": "hAbY3W_browsePanel",
-	"clusterForm": "hAbY3W_clusterForm",
-	"spinner": "hAbY3W_spinner",
-	"groupSection": "hAbY3W_groupSection",
-	"modal": "hAbY3W_modal",
-	"radioRow": "hAbY3W_radioRow",
-	"consoleWrap": "hAbY3W_consoleWrap",
-	"groupChevron": "hAbY3W_groupChevron",
-	"table": "hAbY3W_table",
-	"empty": "hAbY3W_empty",
-	"toolbar": "hAbY3W_toolbar",
-	"termWrap": "hAbY3W_termWrap",
-	"dirType": "hAbY3W_dirType",
-	"cellDetails": "hAbY3W_cellDetails",
-	"badge": "hAbY3W_badge",
-	"progressTrack": "hAbY3W_progressTrack",
-	"panelTitle": "hAbY3W_panelTitle",
-	"termContainer": "hAbY3W_termContainer",
+	"linkButton": "hAbY3W_linkButton",
+	"browsePath": "hAbY3W_browsePath",
 	"dirRow": "hAbY3W_dirRow",
-	"field": "hAbY3W_field",
-	"consoleHeader": "hAbY3W_consoleHeader",
-	"ghostButton": "hAbY3W_ghostButton",
-	"entry": "hAbY3W_entry",
-	"dialog": "hAbY3W_dialog",
+	"dirType": "hAbY3W_dirType",
+	"toolbarSpacer": "hAbY3W_toolbarSpacer",
+	"dialogOverlay": "hAbY3W_dialogOverlay",
+	"table": "hAbY3W_table",
 	"backButton": "hAbY3W_backButton",
-	"consoleInputRow": "hAbY3W_consoleInputRow",
+	"ghostButton": "hAbY3W_ghostButton",
+	"dirName": "hAbY3W_dirName",
+	"groupBySelect": "hAbY3W_groupBySelect",
+	"dirSize": "hAbY3W_dirSize",
+	"tabBody": "hAbY3W_tabBody",
+	"tunnelLabel": "hAbY3W_tunnelLabel",
+	"clusterForm": "hAbY3W_clusterForm",
+	"checkRow": "hAbY3W_checkRow",
 	"formError": "hAbY3W_formError",
-	"groupHeader": "hAbY3W_groupHeader",
 	"progressBar": "hAbY3W_progressBar",
-	"clusterFilters": "hAbY3W_clusterFilters",
-	"dialogOverlay": "hAbY3W_dialogOverlay",
-	"tabBar": "hAbY3W_tabBar",
-	"browseHeader": "hAbY3W_browseHeader",
-	"dshSshSpin": "hAbY3W_dshSshSpin",
-	"entryLabel": "hAbY3W_entryLabel",
-	"hiddenFile": "hAbY3W_hiddenFile",
-	"dirName": "hAbY3W_dirName",
-	"panelHeader": "hAbY3W_panelHeader",
-	"modalFooter": "hAbY3W_modalFooter",
+	"banner": "hAbY3W_banner",
+	"modal": "hAbY3W_modal",
+	"groupName": "hAbY3W_groupName",
+	"input": "hAbY3W_input",
+	"entryIcon": "hAbY3W_entryIcon",
+	"hint": "hAbY3W_hint",
+	"fillBody": "hAbY3W_fillBody",
+	"transferBlock": "hAbY3W_transferBlock",
+	"groupSection": "hAbY3W_groupSection",
 	"modalTitle": "hAbY3W_modalTitle",
+	"progressTrack": "hAbY3W_progressTrack",
+	"actions": "hAbY3W_actions",
 	"tab": "hAbY3W_tab",
-	"tabBody": "hAbY3W_tabBody",
-	"banner": "hAbY3W_banner",
+	"utf8Note": "hAbY3W_utf8Note",
+	"panelTitle": "hAbY3W_panelTitle",
+	"consoleOutput": "hAbY3W_consoleOutput",
+	"hiddenFile": "hAbY3W_hiddenFile",
+	"tunnelRow": "hAbY3W_tunnelRow",
+	"groupCount": "hAbY3W_groupCount",
+	"spinner": "hAbY3W_spinner",
+	"termPlaceholder": "hAbY3W_termPlaceholder",
+	"mono": "hAbY3W_mono",
+	"modalBackdrop": "hAbY3W_modalBackdrop",
+	"cellDetails": "hAbY3W_cellDetails",
 	"termBody": "hAbY3W_termBody",
-	"browseList": "hAbY3W_browseList",
-	"progressMeta": "hAbY3W_progressMeta",
+	"cellPre": "hAbY3W_cellPre",
+	"fieldHint": "hAbY3W_fieldHint",
 	"tableWrap": "hAbY3W_tableWrap",
-	"browsePath": "hAbY3W_browsePath",
-	"tunnelList": "hAbY3W_tunnelList",
-	"entryIcon": "hAbY3W_entryIcon",
-	"checkRow": "hAbY3W_checkRow",
-	"toolbarSpacer": "hAbY3W_toolbarSpacer",
+	"dshSshSpin": "hAbY3W_dshSshSpin",
+	"field": "hAbY3W_field",
+	"fieldLabel": "hAbY3W_fieldLabel",
 	"commandInput": "hAbY3W_commandInput",
-	"termPlaceholder": "hAbY3W_termPlaceholder",
-	"groupBySelect": "hAbY3W_groupBySelect",
-	"transferBlock": "hAbY3W_transferBlock",
-	"fillBody": "hAbY3W_fillBody",
-	"input": "hAbY3W_input",
-	"tunnelLabel": "hAbY3W_tunnelLabel",
+	"consoleWrap": "hAbY3W_consoleWrap",
 	"panel": "hAbY3W_panel",
-	"groupCount": "hAbY3W_groupCount",
-	"linkButton": "hAbY3W_linkButton",
-	"formRow": "hAbY3W_formRow",
 	"dialogTitle": "hAbY3W_dialogTitle",
-	"modalBackdrop": "hAbY3W_modalBackdrop",
-	"fieldHint": "hAbY3W_fieldHint",
-	"cellMuted": "hAbY3W_cellMuted",
-	"mono": "hAbY3W_mono",
+	"browseHeader": "hAbY3W_browseHeader",
+	"inlineTest": "hAbY3W_inlineTest",
+	"browseList": "hAbY3W_browseList",
+	"consoleHeader": "hAbY3W_consoleHeader",
+	"consoleInputRow": "hAbY3W_consoleInputRow",
+	"formRow": "hAbY3W_formRow",
+	"badge": "hAbY3W_badge",
+	"clusterFilters": "hAbY3W_clusterFilters",
+	"primaryButton": "hAbY3W_primaryButton",
+	"toolbar": "hAbY3W_toolbar",
+	"groupToggle": "hAbY3W_groupToggle",
+	"modalFooter": "hAbY3W_modalFooter",
+	"radioRow": "hAbY3W_radioRow",
+	"progressMeta": "hAbY3W_progressMeta",
+	"search": "hAbY3W_search",
+	"browsePanel": "hAbY3W_browsePanel",
+	"termWrap": "hAbY3W_termWrap",
+	"entry": "hAbY3W_entry",
+	"controls": "hAbY3W_controls",
+	"empty": "hAbY3W_empty",
+	"panelHeader": "hAbY3W_panelHeader",
+	"loading": "hAbY3W_loading",
+	"dialog": "hAbY3W_dialog",
+	"formCard": "hAbY3W_formCard",
 	"panelContent": "hAbY3W_panelContent",
-	"fieldLabel": "hAbY3W_fieldLabel",
-	"hint": "hAbY3W_hint",
+	"cellMuted": "hAbY3W_cellMuted",
+	"tabBar": "hAbY3W_tabBar",
+	"tunnelList": "hAbY3W_tunnelList",
+	"entryLabel": "hAbY3W_entryLabel",
+	"groupChevron": "hAbY3W_groupChevron",
+	"iconButton": "hAbY3W_iconButton",
 	"radioLabel": "hAbY3W_radioLabel",
-	"groupName": "hAbY3W_groupName"
+	"groupHeader": "hAbY3W_groupHeader",
+	"termContainer": "hAbY3W_termContainer"
 };
 //#endregion
 //#region src/client/panel/ConsoleTab.tsx

package/lib/index.js

@@ -1307,6 +1307,41 @@ 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;
 /**
+* How long a streaming transfer may deliver nothing before it is treated as
+* stalled.
+*
+* A wall-clock cap on the whole transfer cannot work here: this transport is
+* latency-bound and measured at ~0.73 MiB/s against a real target, so a 700 MiB
+* file legitimately needs about sixteen minutes and any smaller fixed cap fails
+* a transfer that is making steady progress. What a transfer actually needs
+* bounding against is a *stall* — a range that has stopped producing bytes —
+* which is what this idle window measures.
+*/
+const STREAM_IDLE_TIMEOUT_MS = 18e4;
+/**
+* Floor used only to size the runaway backstop, never as a throughput target.
+* Deliberately pessimistic (64 KiB/s): it must not fail a slow link, only a
+* transfer that is somehow still "busy" hours after it should have finished.
+*/
+const STREAM_MIN_BYTES_PER_SEC = 65536;
+/**
+* Budget for one streaming transfer of `bytes` bytes.
+*
+* The idle window is the effective limit; the hard window exists so a wedged
+* transfer cannot stay alive forever, and it scales with the payload because
+* the payload is what sets the legitimate duration.
+* @param bytes - total bytes the transfer must move.
+* @param idleMs - how long the transfer may go without delivering anything.
+* @returns the idle window and the absolute backstop, both in milliseconds.
+*/
+function transferBudget(bytes, idleMs = STREAM_IDLE_TIMEOUT_MS) {
+	const optimisticMs = Math.ceil(Math.max(0, bytes) / STREAM_MIN_BYTES_PER_SEC) * 1e3;
+	return {
+		idleMs,
+		hardMs: Math.max(idleMs * 4, optimisticMs + idleMs)
+	};
+}
+/**
 * 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.
@@ -1318,13 +1353,13 @@ const STREAM_SEND_TIMEOUT_MS = 12e4;
 * @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 budget - idle window and absolute backstop for the transfer.
 * @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) {
+async function streamOnce(conn, remotePath, data, onProgress, budget, authMethod, sendHttp) {
 	const base = baseParams(conn, authMethod);
 	const target = {
 		host: conn.host,
@@ -1336,7 +1371,9 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 		useHttps: conn.useHttps ?? false,
 		rejectUnauthorized: conn.rejectUnauthorized ?? true
 	};
-	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
+	const hardDeadline = Date.now() + budget.hardMs + SETUP_GRACE_MS;
+	let lastProgressAt = Date.now();
+	const stalled = () => Date.now() - lastProgressAt >= budget.idleMs;
 	const state = {
 		shellId: void 0,
 		timedOut: false,
@@ -1365,7 +1402,7 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 		let slice = STREAM_CHUNK_BYTES;
 		let ceiling = STREAM_CHUNK_BYTES;
 		while (offset < total) {
-			if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut();
+			if (state.settled || stalled()) throw new WinrmTimedOut();
 			const take = Math.min(slice, total - offset);
 			const chunk = data.subarray(offset, offset + take);
 			const gz = gzipSync(chunk, { level: 6 });
@@ -1382,6 +1419,7 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 				throw error;
 			}
 			offset += take;
+			lastProgressAt = Date.now();
 			onProgress?.(offset, total);
 			if (slice < ceiling) slice = Math.min(ceiling, slice * 2);
 		}
@@ -1390,15 +1428,15 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 			shellId,
 			commandId
 		};
-		const commandDeadline = Date.now() + timeoutMs;
 		let stdout = "";
 		let stderr = "";
 		for (;;) {
-			if (state.settled || Date.now() >= commandDeadline) throw new WinrmTimedOut();
+			if (state.settled || stalled()) throw new WinrmTimedOut();
 			const chunk = await Command.doReceiveOutputNonBlocking(receive);
 			stdout += chunk.output;
 			stderr += chunk.stderr;
 			if (chunk.isComplete) break;
+			if (chunk.output !== "" || chunk.stderr !== "") lastProgressAt = Date.now();
 		}
 		const parsed = parseEnvelope(stdout);
 		if (parsed === null) throw new Error("streaming upload did not report completion: " + (stripClixml(stderr) || stdout).trim());
@@ -1443,16 +1481,17 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 * @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 idleMs - how long the transfer may go without moving a slice.
 * @returns bytes written, or null when the streaming path is unavailable.
 */
-async function uploadStream(conn, remotePath, data, onProgress, timeoutMs = 6e5) {
+async function uploadStream(conn, remotePath, data, onProgress, idleMs = STREAM_IDLE_TIMEOUT_MS) {
 	const sendHttp = loadSendHttp();
 	if (sendHttp === null) return null;
+	const budget = transferBudget(data.length, idleMs);
 	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);
+		return await streamOnce(conn, remotePath, data, onProgress, budget, authMethod, sendHttp);
 	} catch (error) {
 		if (error instanceof WinrmTimedOut) throw error;
 		lastError = error;
@@ -1472,12 +1511,12 @@ const DOWNLOAD_RECEIVE_TIMEOUT_MS = 12e4;
 * @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 budget - idle window and absolute backstop for this worker's 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) {
+async function downloadWorkerOnce(conn, remotePath, start, length, onData, budget, authMethod, sendHttp) {
 	const base = baseParams(conn, authMethod);
 	const target = {
 		host: conn.host,
@@ -1489,7 +1528,9 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 		useHttps: conn.useHttps ?? false,
 		rejectUnauthorized: conn.rejectUnauthorized ?? true
 	};
-	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
+	const hardDeadline = Date.now() + budget.hardMs + SETUP_GRACE_MS;
+	let lastDataAt = Date.now();
+	const stalled = () => Date.now() - lastDataAt >= budget.idleMs;
 	const state = {
 		shellId: void 0,
 		timedOut: false,
@@ -1524,7 +1565,7 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 		let stdoutEnded = false;
 		let exitCode;
 		while (!stdoutEnded) {
-			if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut();
+			if (state.settled || stalled()) throw new WinrmTimedOut();
 			const result = await receiveOutput(target, shellId, commandId, sendHttp, DOWNLOAD_RECEIVE_TIMEOUT_MS);
 			let sawData = false;
 			for (const stream of result.streams) {
@@ -1538,6 +1579,7 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 					if (stream.end) stdoutEnded = true;
 				} else stderr += stream.data.toString("utf8");
 			}
+			if (sawData) lastDataAt = Date.now();
 			if (inflateError !== void 0) throw inflateError;
 			if (result.exitCode !== void 0) exitCode = result.exitCode;
 			if (!sawData && exitCode !== void 0) break;
@@ -1586,15 +1628,16 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 * @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.
+* @param idleMs - how long a worker may go without delivering bytes.
 * @returns the number of bytes delivered, or null when streaming is unavailable.
 */
-async function downloadStream(conn, remotePath, onData, onProgress, timeoutMs = 6e5) {
+async function downloadStream(conn, remotePath, onData, onProgress, idleMs = STREAM_IDLE_TIMEOUT_MS) {
 	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 budget = transferBudget(total, idleMs);
 	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;
@@ -1618,7 +1661,7 @@ async function downloadStream(conn, remotePath, onData, onProgress, timeoutMs =
 					start,
 					length: Math.min(rangeSize, total - start)
 				});
-				await Promise.all(ranges.map((range) => downloadWorkerOnce(conn, remotePath, range.start, range.length, report, timeoutMs, authMethod, sendHttp)));
+				await Promise.all(ranges.map((range) => downloadWorkerOnce(conn, remotePath, range.start, range.length, report, budget, authMethod, sendHttp)));
 				return transferred;
 			} catch (error) {
 				if (error instanceof WinrmTimedOut) throw error;
@@ -1781,7 +1824,7 @@ async function smbReachable(host) {
 }
 /** 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)");
+	return /* @__PURE__ */ new Error("SMB is not reachable on " + host + ":445 (the admin share needs TCP 445 open and the Server service running); retry with channel \"winrm\" to transfer over WinRM instead");
 }
 /**
 * Copy one local file to a remote Windows host over SMB, verifying the
@@ -2430,16 +2473,19 @@ var WinRmEngine = class {
 					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0
 				});
 			};
+			let delivered = 0;
 			try {
 				const conn = connOf(entry);
-				if (await downloadStream(conn, remotePath, put, report) === null) {
+				const streamed = await downloadStream(conn, remotePath, put, report);
+				if (streamed === null) {
 					let offset = 0;
 					await downloadChunks(conn, remotePath, (b64) => {
 						const buffer = Buffer.from(b64, "base64");
 						put(offset, buffer);
 						offset += buffer.length;
 					}, report);
-				}
+					delivered = bytes;
+				} else delivered = streamed;
 				await queue;
 				if (sink === null) sink = await open(localPath, "w", 384);
 				completed = true;
@@ -2451,12 +2497,12 @@ var WinRmEngine = class {
 			onProgress?.({
 				phase: "done",
 				file: remotePath,
-				transferred: bytes,
-				total: bytes,
+				transferred: delivered,
+				total: delivered,
 				percent: 100
 			});
 			return {
-				bytes,
+				bytes: delivered,
 				channel: "winrm"
 			};
 		});
@@ -3656,7 +3702,7 @@ function winrmUploadTool(engine) {
 					"smb",
 					"winrm"
 				],
-				description: "Transfer channel: smb (admin share), winrm (streamed over the WinRS stdin channel), or auto (default, SMB first with WinRM fallback)."
+				description: "Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over the WinRS stdin channel."
 			}
 		},
 		output: {
@@ -3700,7 +3746,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. 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.",
+		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). Large files are fine: the WinRM path runs for as long as bytes keep arriving and only fails once a range stalls. Directory download is not supported — download files individually. Triggers: download file from Windows server, fetch remote log/artifact.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3724,7 +3770,7 @@ function winrmDownloadTool(engine) {
 					"smb",
 					"winrm"
 				],
-				description: "Transfer channel: smb (admin share), winrm (streamed over parallel WinRS ranges), or auto (default, SMB first with WinRM fallback)."
+				description: "Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over parallel WinRS byte ranges."
 			}
 		},
 		output: {
@@ -4258,7 +4304,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_read/winrm_write/winrm_edit 远程文本文件读写（按行分页、编码感知、精确串替换，作用于远端主机而非本机，本机文件仍用 read/write/edit）、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 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
+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_read/winrm_write/winrm_edit 远程文本文件读写（按行分页、编码感知、精确串替换，作用于远端主机而非本机，本机文件仍用 read/write/edit）、winrm_upload/winrm_download 文件传输（channel=auto 时若目标 445 可达走 SMB 管理共享，否则走 WinRM 流式传输；channel=smb 在 445 关闭时直接报错、需改用 winrm；大文件可下载，流式通道按字节持续推进、仅在字节断流时才判超时、完成后经 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.

package/lib/types/engine/client.d.ts

@@ -53,6 +53,32 @@ export declare const TRANSFER_CHUNK: number;
 export declare function remoteFileSize(conn: WinRMParams, remotePath: string, timeoutMs?: number): Promise<number | null>;
 export declare function downloadChunks(conn: WinRMParams, remotePath: string, onChunk: (b64: string, bytes: number) => void, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number>;
 export declare function uploadBuffer(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number>;
+/**
+ * How long a streaming transfer may deliver nothing before it is treated as
+ * stalled.
+ *
+ * A wall-clock cap on the whole transfer cannot work here: this transport is
+ * latency-bound and measured at ~0.73 MiB/s against a real target, so a 700 MiB
+ * file legitimately needs about sixteen minutes and any smaller fixed cap fails
+ * a transfer that is making steady progress. What a transfer actually needs
+ * bounding against is a *stall* — a range that has stopped producing bytes —
+ * which is what this idle window measures.
+ */
+export declare const STREAM_IDLE_TIMEOUT_MS = 180000;
+/**
+ * Budget for one streaming transfer of `bytes` bytes.
+ *
+ * The idle window is the effective limit; the hard window exists so a wedged
+ * transfer cannot stay alive forever, and it scales with the payload because
+ * the payload is what sets the legitimate duration.
+ * @param bytes - total bytes the transfer must move.
+ * @param idleMs - how long the transfer may go without delivering anything.
+ * @returns the idle window and the absolute backstop, both in milliseconds.
+ */
+export declare function transferBudget(bytes: number, idleMs?: number): {
+    idleMs: number;
+    hardMs: number;
+};
 /**
  * Upload a buffer over a single WinRS stdin stream.
  *
@@ -68,10 +94,10 @@ export declare function uploadBuffer(conn: WinRMParams, remotePath: string, data
  * @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 idleMs - how long the transfer may go without moving a slice.
  * @returns bytes written, or null when the streaming path is unavailable.
  */
-export declare function uploadStream(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number | null>;
+export declare function uploadStream(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, idleMs?: number): Promise<number | null>;
 /**
  * Stream a remote file to a consumer, in parallel byte ranges.
  *
@@ -90,7 +116,7 @@ export declare function uploadStream(conn: WinRMParams, remotePath: string, data
  * @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.
+ * @param idleMs - how long a worker may go without delivering bytes.
  * @returns the number of bytes delivered, or null when streaming is unavailable.
  */
-export declare function downloadStream(conn: WinRMParams, remotePath: string, onData: (offset: number, data: Buffer) => void, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number | null>;
+export declare function downloadStream(conn: WinRMParams, remotePath: string, onData: (offset: number, data: Buffer) => void, onProgress?: (transferred: number, total: number) => void, idleMs?: number): Promise<number | null>;

package/lib/types/index.d.ts

@@ -35,7 +35,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     enabled: z<boolean, boolean, "volatile-defined">;
 }>>, "plain">;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export declare const WINRM_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-winrm \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B Windows \u8FD0\u7EF4\uFF0CWinRM/PowerShell Remoting\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CWindows\u300D\u5165\u53E3\uFF1B\u4EFF\u7167 dsh-ssh \u63D2\u4EF6\u5F00\u53D1\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-winrm.json\uFF08GUI \u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF09\uFF1Bwinrm_list \u5217\u51FA\u4E3B\u673A\u3001winrm_exec \u6267\u884C PowerShell \u547D\u4EE4\uFF08UTF-8 \u4FE1\u5C01\uFF0C\u4E2D\u6587\u4E0D\u4E71\u7801\uFF09\u3001winrm_service \u670D\u52A1\u7BA1\u7406\uFF08start/stop/restart/\u542F\u52A8\u7C7B\u578B\uFF09\u3001winrm_process \u8FDB\u7A0B\u7BA1\u7406\uFF08list/kill\uFF09\u3001winrm_read/winrm_write/winrm_edit \u8FDC\u7A0B\u6587\u672C\u6587\u4EF6\u8BFB\u5199\uFF08\u6309\u884C\u5206\u9875\u3001\u7F16\u7801\u611F\u77E5\u3001\u7CBE\u786E\u4E32\u66FF\u6362\uFF0C\u4F5C\u7528\u4E8E\u8FDC\u7AEF\u4E3B\u673A\u800C\u975E\u672C\u673A\uFF0C\u672C\u673A\u6587\u4EF6\u4ECD\u7528 read/write/edit\uFF09\u3001winrm_upload/winrm_download \u6587\u4EF6\u4F20\u8F93\uFF08SMB \u7BA1\u7406\u5171\u4EAB\u53EF\u8FBE\u65F6\u4F18\u5148\uFF0C\u5426\u5219\u8D70 WinRM \u6D41\u5F0F\u4F20\u8F93\uFF0C\u65E0 SMB \u4F9D\u8D56\uFF0C\u5927\u6587\u4EF6\u7ECF SHA256 \u6821\u9A8C\uFF09\u3001winrm_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1BWeb \u63A7\u5236\u53F0\u8D70 WebSocket\u3002\u8BA4\u8BC1\uFF1A\u901A\u8FC7\u539F\u751F Node.js WinRM \u5BA2\u6237\u7AEF\uFF08winrm-client\uFF09\u7684 NTLM/Negotiate \u4E0E Basic \u5B9E\u73B0\uFF0C\u517C\u5BB9\u672C\u5730\u8D26\u6237\u4E0E\u57DF\u8D26\u6237\uFF1B\u4F20\u8F93\u652F\u6301 http(5985)/https(5986)\u3002\u524D\u63D0\uFF1A\u76EE\u6807\u673A\u9700\u542F\u7528 WinRM\uFF08scripts/enable-winrm.ps1\uFF09\uFF0C\u672C\u673A\u65E0\u9700 Python \u2014\u2014 WinRM \u8D70\u7EAF Node \u4F9D\u8D56\u3002HTTP \u4EC5\u5EFA\u8BAE\u53D7\u4FE1\u5185\u7F51\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CWindows \u670D\u52A1\u5668 / WinRM / PowerShell \u8FDC\u7A0B / \u670D\u52A1\u7BA1\u7406 / \u8FDB\u7A0B\u7BA1\u7406\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const WINRM_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-winrm \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B Windows \u8FD0\u7EF4\uFF0CWinRM/PowerShell Remoting\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CWindows\u300D\u5165\u53E3\uFF1B\u4EFF\u7167 dsh-ssh \u63D2\u4EF6\u5F00\u53D1\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-winrm.json\uFF08GUI \u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF09\uFF1Bwinrm_list \u5217\u51FA\u4E3B\u673A\u3001winrm_exec \u6267\u884C PowerShell \u547D\u4EE4\uFF08UTF-8 \u4FE1\u5C01\uFF0C\u4E2D\u6587\u4E0D\u4E71\u7801\uFF09\u3001winrm_service \u670D\u52A1\u7BA1\u7406\uFF08start/stop/restart/\u542F\u52A8\u7C7B\u578B\uFF09\u3001winrm_process \u8FDB\u7A0B\u7BA1\u7406\uFF08list/kill\uFF09\u3001winrm_read/winrm_write/winrm_edit \u8FDC\u7A0B\u6587\u672C\u6587\u4EF6\u8BFB\u5199\uFF08\u6309\u884C\u5206\u9875\u3001\u7F16\u7801\u611F\u77E5\u3001\u7CBE\u786E\u4E32\u66FF\u6362\uFF0C\u4F5C\u7528\u4E8E\u8FDC\u7AEF\u4E3B\u673A\u800C\u975E\u672C\u673A\uFF0C\u672C\u673A\u6587\u4EF6\u4ECD\u7528 read/write/edit\uFF09\u3001winrm_upload/winrm_download \u6587\u4EF6\u4F20\u8F93\uFF08channel=auto \u65F6\u82E5\u76EE\u6807 445 \u53EF\u8FBE\u8D70 SMB \u7BA1\u7406\u5171\u4EAB\uFF0C\u5426\u5219\u8D70 WinRM \u6D41\u5F0F\u4F20\u8F93\uFF1Bchannel=smb \u5728 445 \u5173\u95ED\u65F6\u76F4\u63A5\u62A5\u9519\u3001\u9700\u6539\u7528 winrm\uFF1B\u5927\u6587\u4EF6\u53EF\u4E0B\u8F7D\uFF0C\u6D41\u5F0F\u901A\u9053\u6309\u5B57\u8282\u6301\u7EED\u63A8\u8FDB\u3001\u4EC5\u5728\u5B57\u8282\u65AD\u6D41\u65F6\u624D\u5224\u8D85\u65F6\u3001\u5B8C\u6210\u540E\u7ECF SHA256 \u6821\u9A8C\uFF09\u3001winrm_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1BWeb \u63A7\u5236\u53F0\u8D70 WebSocket\u3002\u8BA4\u8BC1\uFF1A\u901A\u8FC7\u539F\u751F Node.js WinRM \u5BA2\u6237\u7AEF\uFF08winrm-client\uFF09\u7684 NTLM/Negotiate \u4E0E Basic \u5B9E\u73B0\uFF0C\u517C\u5BB9\u672C\u5730\u8D26\u6237\u4E0E\u57DF\u8D26\u6237\uFF1B\u4F20\u8F93\u652F\u6301 http(5985)/https(5986)\u3002\u524D\u63D0\uFF1A\u76EE\u6807\u673A\u9700\u542F\u7528 WinRM\uFF08scripts/enable-winrm.ps1\uFF09\uFF0C\u672C\u673A\u65E0\u9700 Python \u2014\u2014 WinRM \u8D70\u7EAF Node \u4F9D\u8D56\u3002HTTP \u4EC5\u5EFA\u8BAE\u53D7\u4FE1\u5185\u7F51\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CWindows \u670D\u52A1\u5668 / WinRM / PowerShell \u8FDC\u7A0B / \u670D\u52A1\u7BA1\u7406 / \u8FDB\u7A0B\u7BA1\u7406\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /**
  * Mount the WinRM engine, routes, tools, and announcement.
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-winrm",
   "description": "Remote Windows administration for the dsh web GUI: WinRM/PowerShell Remoting host config store (~/.dsh/dsh-winrm.json), PowerShell exec / streaming console / service & process management / remote text read-write-edit / streamed file transfer / cluster execution, plus agent tools (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_read, winrm_write, winrm_edit, winrm_upload, winrm_download, winrm_cluster). Runs entirely on a native Node.js WinRM client (winrm-client) — no Python/pywinrm required. Standalone Cordis plugin — mounted via cordis.patch.yml + a profile node_modules link, no dsh source changes.",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/src/engine/client.ts

@@ -337,6 +337,41 @@ const STREAM_GZIP_MIN_RATIO = 0.85
 /** Per-Send HTTP budget; a single slice is small, so this only bounds a stalled connection. */
 const STREAM_SEND_TIMEOUT_MS = 120_000
 
+/**
+ * How long a streaming transfer may deliver nothing before it is treated as
+ * stalled.
+ *
+ * A wall-clock cap on the whole transfer cannot work here: this transport is
+ * latency-bound and measured at ~0.73 MiB/s against a real target, so a 700 MiB
+ * file legitimately needs about sixteen minutes and any smaller fixed cap fails
+ * a transfer that is making steady progress. What a transfer actually needs
+ * bounding against is a *stall* — a range that has stopped producing bytes —
+ * which is what this idle window measures.
+ */
+export const STREAM_IDLE_TIMEOUT_MS = 180_000
+
+/**
+ * Floor used only to size the runaway backstop, never as a throughput target.
+ * Deliberately pessimistic (64 KiB/s): it must not fail a slow link, only a
+ * transfer that is somehow still "busy" hours after it should have finished.
+ */
+const STREAM_MIN_BYTES_PER_SEC = 65_536
+
+/**
+ * Budget for one streaming transfer of `bytes` bytes.
+ *
+ * The idle window is the effective limit; the hard window exists so a wedged
+ * transfer cannot stay alive forever, and it scales with the payload because
+ * the payload is what sets the legitimate duration.
+ * @param bytes - total bytes the transfer must move.
+ * @param idleMs - how long the transfer may go without delivering anything.
+ * @returns the idle window and the absolute backstop, both in milliseconds.
+ */
+export function transferBudget(bytes: number, idleMs = STREAM_IDLE_TIMEOUT_MS): { idleMs: number; hardMs: number } {
+  const optimisticMs = Math.ceil(Math.max(0, bytes) / STREAM_MIN_BYTES_PER_SEC) * 1000
+  return { idleMs, hardMs: Math.max(idleMs * 4, optimisticMs + idleMs) }
+}
+
 /**
  * One streaming transfer over a single shell: create → run the receiver →
  * push the receiver script, the header frame and every data frame down stdin →
@@ -349,7 +384,7 @@ const STREAM_SEND_TIMEOUT_MS = 120_000
  * @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 budget - idle window and absolute backstop for the transfer.
  * @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.
@@ -360,7 +395,7 @@ async function streamOnce(
   remotePath: string,
   data: Buffer,
   onProgress: ((transferred: number, total: number) => void) | undefined,
-  timeoutMs: number,
+  budget: { idleMs: number; hardMs: number },
   authMethod: WinrmAuth,
   sendHttp: ReturnType<typeof loadSendHttp> & object,
 ): Promise<number> {
@@ -375,7 +410,12 @@ async function streamOnce(
     useHttps: conn.useHttps ?? false,
     rejectUnauthorized: conn.rejectUnauthorized ?? true,
   }
-  const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS
+  const hardDeadline = Date.now() + budget.hardMs + SETUP_GRACE_MS
+  // Progress is what keeps a transfer alive: the send loop and the final
+  // receive loop both refresh this, and only a window with no progress at all
+  // is treated as a stall.
+  let lastProgressAt = Date.now()
+  const stalled = (): boolean => Date.now() - lastProgressAt >= budget.idleMs
   const state = { shellId: undefined as string | undefined, timedOut: false, settled: false }
   const total = data.length
 
@@ -405,7 +445,7 @@ async function streamOnce(
     let slice = STREAM_CHUNK_BYTES
     let ceiling = STREAM_CHUNK_BYTES
     while (offset < total) {
-      if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut()
+      if (state.settled || stalled()) throw new WinrmTimedOut()
       const take = Math.min(slice, total - offset)
       const chunk = data.subarray(offset, offset + take)
       const gz = gzipSync(chunk, { level: 6 })
@@ -422,6 +462,7 @@ async function streamOnce(
         throw error
       }
       offset += take
+      lastProgressAt = Date.now()
       onProgress?.(offset, total)
       if (slice < ceiling) slice = Math.min(ceiling, slice * 2)
     }
@@ -429,15 +470,15 @@ async function streamOnce(
     // 4. The receiver stops on its own once the declared byte count lands, so
     //    there is nothing to close — just wait for its envelope.
     const receive = { ...base, shellId, commandId }
-    const commandDeadline = Date.now() + timeoutMs
     let stdout = ''
     let stderr = ''
     for (;;) {
-      if (state.settled || Date.now() >= commandDeadline) throw new WinrmTimedOut()
+      if (state.settled || stalled()) throw new WinrmTimedOut()
       const chunk = await Command.doReceiveOutputNonBlocking(receive)
       stdout += chunk.output
       stderr += chunk.stderr
       if (chunk.isComplete) break
+      if (chunk.output !== '' || chunk.stderr !== '') lastProgressAt = Date.now()
     }
 
     const parsed = parseEnvelope(stdout)
@@ -488,7 +529,7 @@ async function streamOnce(
  * @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 idleMs - how long the transfer may go without moving a slice.
  * @returns bytes written, or null when the streaming path is unavailable.
  */
 export async function uploadStream(
@@ -496,15 +537,16 @@ export async function uploadStream(
   remotePath: string,
   data: Buffer,
   onProgress?: (transferred: number, total: number) => void,
-  timeoutMs = 600_000,
+  idleMs = STREAM_IDLE_TIMEOUT_MS,
 ): Promise<number | null> {
   const sendHttp = loadSendHttp()
   if (sendHttp === null) return null
+  const budget = transferBudget(data.length, idleMs)
   const candidates: WinrmAuth[] = conn.useHttps ? ['basic', 'ntlm'] : ['ntlm', 'basic']
   let lastError: unknown
   for (const authMethod of candidates) {
     try {
-      return await streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMethod, sendHttp)
+      return await streamOnce(conn, remotePath, data, onProgress, budget, authMethod, sendHttp)
     } catch (error) {
       if (error instanceof WinrmTimedOut) throw error
       lastError = error
@@ -527,7 +569,7 @@ const DOWNLOAD_RECEIVE_TIMEOUT_MS = 120_000
  * @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 budget - idle window and absolute backstop for this worker's 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.
@@ -538,7 +580,7 @@ async function downloadWorkerOnce(
   start: number,
   length: number,
   onData: (offset: number, data: Buffer) => void,
-  timeoutMs: number,
+  budget: { idleMs: number; hardMs: number },
   authMethod: WinrmAuth,
   sendHttp: ReturnType<typeof loadSendHttp> & object,
 ): Promise<number> {
@@ -553,7 +595,12 @@ async function downloadWorkerOnce(
     useHttps: conn.useHttps ?? false,
     rejectUnauthorized: conn.rejectUnauthorized ?? true,
   }
-  const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS
+  const hardDeadline = Date.now() + budget.hardMs + SETUP_GRACE_MS
+  // Same rule as the upload path: bytes arriving keep the worker alive, and
+  // only a window with no bytes at all counts as a stall. A flat whole-transfer
+  // cap would fail a large file on a slow link even while it is moving.
+  let lastDataAt = Date.now()
+  const stalled = (): boolean => Date.now() - lastDataAt >= budget.idleMs
   const state = { shellId: undefined as string | undefined, timedOut: false, settled: false }
 
   const inner = async (): Promise<number> => {
@@ -589,7 +636,7 @@ async function downloadWorkerOnce(
       // A worker that lost the deadline race keeps running in the background
       // unless it checks; without this it would go on fetching and pushing
       // bytes into a file the caller has already given up on.
-      if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut()
+      if (state.settled || stalled()) throw new WinrmTimedOut()
       const result = await receiveOutput(target, shellId, commandId, sendHttp, DOWNLOAD_RECEIVE_TIMEOUT_MS)
       let sawData = false
       for (const stream of result.streams) {
@@ -605,6 +652,7 @@ async function downloadWorkerOnce(
           stderr += stream.data.toString('utf8')
         }
       }
+      if (sawData) lastDataAt = Date.now()
       if (inflateError !== undefined) throw inflateError
       if (result.exitCode !== undefined) exitCode = result.exitCode
       // A finished command whose final response carried nothing means the
@@ -663,7 +711,7 @@ async function downloadWorkerOnce(
  * @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.
+ * @param idleMs - how long a worker may go without delivering bytes.
  * @returns the number of bytes delivered, or null when streaming is unavailable.
  */
 export async function downloadStream(
@@ -671,13 +719,15 @@ export async function downloadStream(
   remotePath: string,
   onData: (offset: number, data: Buffer) => void,
   onProgress?: (transferred: number, total: number) => void,
-  timeoutMs = 600_000,
+  idleMs = STREAM_IDLE_TIMEOUT_MS,
 ): Promise<number | null> {
   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
+  // The payload size, not a constant, is what sets a legitimate duration here.
+  const budget = transferBudget(total, idleMs)
   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
@@ -708,7 +758,7 @@ export async function downloadStream(
         }
         await Promise.all(
           ranges.map(range =>
-            downloadWorkerOnce(conn, remotePath, range.start, range.length, report, timeoutMs, authMethod, sendHttp),
+            downloadWorkerOnce(conn, remotePath, range.start, range.length, report, budget, authMethod, sendHttp),
           ),
         )
         return transferred

package/src/engine.ts

@@ -536,6 +536,7 @@ export class WinRmEngine {
       const report = (transferred: number, total: number): void => {
         onProgress?.({ phase: 'transferring', file: remotePath, transferred, total, percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0 })
       }
+      let delivered = 0
       try {
         const conn = connOf(entry)
         const streamed = await downloadStream(conn, remotePath, put, report)
@@ -551,6 +552,12 @@ export class WinRmEngine {
             },
             report,
           )
+          delivered = bytes
+        } else {
+          // `bytes` counts every positional write, and a retry re-sends the
+          // ranges from their start — so it would report more than the file
+          // holds. The successful attempt's own total is the file size.
+          delivered = streamed
         }
         await queue
         // A zero-byte remote file produces no writes, so the sink is still
@@ -570,8 +577,8 @@ export class WinRmEngine {
         // already truncated that file to nothing.
         if (!completed && sink !== null) await rm(localPath, { force: true }).catch(() => undefined)
       }
-      onProgress?.({ phase: 'done', file: remotePath, transferred: bytes, total: bytes, percent: 100 })
-      return { bytes, channel: 'winrm' }
+      onProgress?.({ phase: 'done', file: remotePath, transferred: delivered, total: delivered, percent: 100 })
+      return { bytes: delivered, channel: 'winrm' }
     })
   }
 

package/src/index.ts

@@ -68,7 +68,7 @@ const DEFAULT_ENABLED = true
 const SECTION_ORDER = 151
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export 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_read/winrm_write/winrm_edit 远程文本文件读写（按行分页、编码感知、精确串替换，作用于远端主机而非本机，本机文件仍用 read/write/edit）、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 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。'
+export 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_read/winrm_write/winrm_edit 远程文本文件读写（按行分页、编码感知、精确串替换，作用于远端主机而非本机，本机文件仍用 read/write/edit）、winrm_upload/winrm_download 文件传输（channel=auto 时若目标 445 可达走 SMB 管理共享，否则走 WinRM 流式传输；channel=smb 在 445 关闭时直接报错、需改用 winrm；大文件可下载，流式通道按字节持续推进、仅在字节断流时才判超时、完成后经 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.

package/src/smb.ts

@@ -134,7 +134,10 @@ export async function smbReachable(host: string): Promise<boolean> {
 
 /** Error thrown when SMB was requested or probed and the target is not listening. */
 export function smbUnavailable(host: string): Error {
-  return new Error('SMB is not reachable on ' + host + ':445 (the admin share needs TCP 445 open and the Server service running)')
+  return new Error(
+    'SMB is not reachable on ' + host + ':445 (the admin share needs TCP 445 open and the Server service running); '
+    + 'retry with channel "winrm" to transfer over WinRM instead',
+  )
 }
 
 /**

package/src/tools.ts

@@ -273,7 +273,7 @@ export function winrmUploadTool(engine: WinRmEngine) {
       alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
       localPath: { type: 'string', required: true, description: 'Absolute local file path on this machine.' },
       remotePath: { type: 'string', required: true, description: 'Destination path on the remote host, e.g. C:\\temp\\file.txt (parent dirs are created).' },
-      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (streamed over the WinRS stdin channel), or auto (default, SMB first with WinRM fallback).' },
+      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over the WinRS stdin channel.' },
     },
     output: {
       schema: {
@@ -306,13 +306,13 @@ export function winrmUploadTool(engine: WinRmEngine) {
 export function winrmDownloadTool(engine: WinRmEngine) {
   return defineTool({
     name: 'winrm_download',
-    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. ' +
+    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). Large files are fine: the WinRM path runs for as long as bytes keep arriving and only fails once a range stalls. Directory download is not supported — download files individually. ' +
       'Triggers: download file from Windows server, fetch remote log/artifact.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
       remotePath: { type: 'string', required: true, description: 'Remote file path, e.g. C:\\temp\\file.txt.' },
       localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
-      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (streamed over parallel WinRS ranges), or auto (default, SMB first with WinRM fallback).' },
+      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over parallel WinRS byte ranges.' },
     },
     output: {
       schema: {