dsh-winrm 0.1.0

package/lib/index.js

@@ -0,0 +1,2458 @@
+import z from "@deepseek-ai/schemastery";
+import { Command, Shell } from "winrm-client";
+import { spawn } from "node:child_process";
+import { copyFile, readFile, stat, unlink } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+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
+/** PS single-quoted literal (doubles embedded quotes). */
+function sq(value) {
+	return "'" + value.replace(/'/g, "''") + "'";
+}
+/** Base64 of a UTF-16LE PowerShell script, for -EncodedCommand. */
+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.
+*/
+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))",
+		""
+	].join("\r\n");
+}
+/** One-shot script body for the PowerShell session already created by WinRM. */
+function winrmPowerShellScript(userScript) {
+	return wrapEnvelope(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);
+}
+/** JSON: full service table (CIM). */
+function psListServices() {
+	return [
+		"$__s = Get-CimInstance Win32_Service | Select-Object Name, DisplayName, State, StartMode, StartName | ForEach-Object {",
+		"  [PSCustomObject]@{ name=$_.Name; displayName=$_.DisplayName; status=[string]$_.State; startMode=[string]$_.StartMode; startName=[string]$_.StartName }",
+		"}",
+		"ConvertTo-Json -InputObject $__s -Compress -Depth 3",
+		""
+	].join("\r\n");
+}
+/** JSON: one service after an action. */
+function psServiceAction(name, action) {
+	const statements = [];
+	if (action === "start") statements.push("Start-Service -Name " + sq(name) + " -ErrorAction Stop");
+	if (action === "stop") statements.push("Stop-Service -Name " + sq(name) + " -Force -ErrorAction Stop");
+	if (action === "restart") statements.push("Restart-Service -Name " + sq(name) + " -Force -ErrorAction Stop");
+	if (action === "set-auto") statements.push("Set-Service -Name " + sq(name) + " -StartupType Automatic -ErrorAction Stop");
+	if (action === "set-manual") statements.push("Set-Service -Name " + sq(name) + " -StartupType Manual -ErrorAction Stop");
+	if (action === "set-disabled") statements.push("Set-Service -Name " + sq(name) + " -StartupType Disabled -ErrorAction Stop");
+	statements.push("$__s = Get-CimInstance Win32_Service -Filter " + sq("Name=" + name.replace(/'/g, "''")) + " | Select-Object Name, DisplayName, State, StartMode, StartName");
+	statements.push("ConvertTo-Json -InputObject $__s -Compress -Depth 3");
+	return statements.join("\r\n");
+}
+/** JSON: process table. */
+function psListProcesses() {
+	return [
+		"$__p = Get-Process | Sort-Object Id | Select-Object Id, ProcessName, CPU, WS, StartTime, Path | ForEach-Object {",
+		"  [PSCustomObject]@{ id=$_.Id; name=$_.ProcessName; cpu=if($null -eq $_.CPU){$null}else{[math]::Round([double]$_.CPU,1)}; memMB=[math]::Round($_.WS/1MB,1); startTime=if($_.StartTime){$_.StartTime.ToString('yyyy-MM-dd HH:mm:ss')}else{$null}; path=[string]$_.Path }",
+		"}",
+		"ConvertTo-Json -InputObject $__p -Compress -Depth 3",
+		""
+	].join("\r\n");
+}
+/** Kill one process by id. */
+function psKillProcess(id) {
+	return "Stop-Process -Id " + String(id) + " -Force -ErrorAction Stop; \"killed \" + " + String(id);
+}
+/** JSON: directory listing. */
+function psListDir(dir) {
+	return [
+		"$__d = " + sq(dir),
+		"$__items = Get-ChildItem -LiteralPath $__d -Force -ErrorAction Stop | Select-Object Name, PSIsContainer, Length, LastWriteTime | ForEach-Object {",
+		"  [PSCustomObject]@{ name=[string]$_.Name; type=if($_.PSIsContainer){'dir'}elseif(-not $_.PSIsContainer -and $_.Length -ge 0){'file'}else{'other'}; size=if($_.PSIsContainer){0}else{[long]$_.Length}; mtimeMs=[long](([DateTimeOffset]$_.LastWriteTime).ToUnixTimeMilliseconds()) }",
+		"}",
+		"ConvertTo-Json -InputObject $__items -Compress -Depth 3",
+		""
+	].join("\r\n");
+}
+/** Plain: remote file size in bytes (0 when missing). */
+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 }",
+		""
+	].join("\r\n");
+}
+/** Plain: base64 of up to `count` bytes at `offset` (download chunk). */
+function psReadChunk(p, offset, count) {
+	return [
+		"$__p = " + sq(p),
+		"$__fs = [System.IO.File]::OpenRead($__p)",
+		"try {",
+		"  $__fs.Position = [long]" + String(offset),
+		"  $__buf = New-Object byte[] " + String(count),
+		"  $__n = $__fs.Read($__buf, 0, $__buf.Length)",
+		"  [System.Convert]::ToBase64String($__buf, 0, $__n)",
+		"} finally { $__fs.Dispose() }",
+		""
+	].join("\r\n");
+}
+/**
+* Plain: append `b64` bytes to `p` (Create on first chunk, Append after),
+* prints the number of bytes written.
+*/
+function psWriteChunk(p, b64, append) {
+	return [
+		"$__p = " + sq(p),
+		"$__d = [System.IO.Path]::GetDirectoryName($__p)",
+		"if (-not [string]::IsNullOrEmpty($__d)) { [System.IO.Directory]::CreateDirectory($__d) | Out-Null }",
+		"$__b = [System.Convert]::FromBase64String(" + sq(b64) + ")",
+		"$__mode = " + (append ? "[System.IO.FileMode]::Append" : "[System.IO.FileMode]::Create"),
+		"$__fs = New-Object System.IO.FileStream($__p, $__mode, [System.IO.FileAccess]::Write, [System.IO.FileShare]::Read)",
+		"try { $__fs.Write($__b, 0, $__b.Length) } finally { $__fs.Dispose() }",
+		"[string]$__b.Length",
+		""
+	].join("\r\n");
+}
+/**
+* Parse the envelope output: { exitCode, text } or null when absent.
+*
+* 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.
+*/
+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
+		};
+	}
+}
+/** 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.
+*
+* PowerShell marks its stderr stream with a `#< CLIXML` header line and
+* serializes the remote host's own progress/verbose records into `<Objs>`
+* blocks. Both are removed here. Anything else on the stream is genuine
+* process-level stderr and is preserved verbatim — text written between the
+* 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.
+* @returns the stderr text without CLIXML host records.
+*/
+function stripClixml(stderr) {
+	return stderr.replace(CLIXML_HEADER, "").replace(CLIXML_RECORDS, "").trim();
+}
+//#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.
+*
+* 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
+* still connects. Credentials are passed to the library in-process — they
+* never appear in a child-process argument list.
+*/
+/** Extra wall-clock budget so connection setup does not eat the command's timeout window. */
+const SETUP_GRACE_MS = 5e3;
+/** Upper bound on the best-effort shell-delete round trip after a timed-out call. */
+const DELETE_TIMEOUT_MS = 1e4;
+/** Sentinel: the command exceeded its deadline (distinct from auth/transport errors). */
+var WinrmTimedOut = class extends Error {
+	constructor() {
+		super("WinRM request timed out");
+		this.name = "WinrmTimedOut";
+	}
+};
+/** Small cancellable delay used to bound the shell-delete cleanup. */
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+/**
+* Race a promise against a deadline; the loser's later settlement is
+* ignored (Promise.race attaches a handler to both), so a hung WinRM call
+* cannot surface as an unhandled rejection.
+* @param promise - the operation to bound.
+* @param ms - milliseconds before rejecting with {@link WinrmTimedOut}.
+* @returns the operation result, or rejects with WinrmTimedOut on deadline.
+*/
+async function raceDeadline(promise, ms) {
+	let timer;
+	const timeout = new Promise((_resolve, reject) => {
+		timer = setTimeout(() => {
+			reject(new WinrmTimedOut());
+		}, ms);
+	});
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+/** Build winrm-client's base params for one auth scheme. */
+function baseParams(conn, authMethod) {
+	return {
+		host: conn.host,
+		port: conn.port,
+		path: conn.path,
+		username: conn.username,
+		password: conn.password,
+		authMethod,
+		useHttps: conn.useHttps ?? false,
+		rejectUnauthorized: conn.rejectUnauthorized ?? true
+	};
+}
+/**
+* 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.
+* @param conn - connection parameters.
+* @param envelope - the wrapped UTF-8 envelope script (already prepared).
+* @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) {
+	const base = baseParams(conn, authMethod);
+	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 command = powershellCommandLine(envelope);
+		const commandId = await Command.doExecuteCommand({
+			...base,
+			shellId,
+			command
+		});
+		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) return {
+				stdout,
+				stderr
+			};
+		}
+	})();
+	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)]);
+		}
+	}
+}
+/**
+* Run one envelope over WinRM, trying each auth scheme in order until one
+* 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 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) {
+	const candidates = conn.useHttps ? ["basic", "ntlm"] : ["ntlm", "basic"];
+	let lastError;
+	for (const authMethod of candidates) try {
+		return await attemptOnce(conn, envelope, timeoutMs, authMethod);
+	} catch (error) {
+		if (error instanceof WinrmTimedOut) throw error;
+		lastError = error;
+	}
+	throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error("all WinRM authentication methods failed");
+}
+async function runScript(conn, script, options = {}) {
+	const started = Date.now();
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const envelope = winrmPowerShellScript(script);
+	let outcome;
+	try {
+		outcome = await runWinrm(conn, envelope, timeoutMs);
+	} catch (error) {
+		if (error instanceof WinrmTimedOut) return {
+			stdout: "",
+			stderr: "",
+			exitCode: null,
+			timedOut: true,
+			durationMs: Date.now() - started
+		};
+		throw error;
+	}
+	const raw = outcome.stdout;
+	const parsed = parseEnvelope(raw);
+	const exitCode = parsed !== null ? parsed.exitCode : 1;
+	const stderr = parsed !== null ? stripClixml(outcome.stderr) : outcome.stderr;
+	options.onChunk?.({
+		output: raw,
+		stderr
+	});
+	return {
+		stdout: parsed !== null ? parsed.text : raw,
+		stderr,
+		exitCode,
+		timedOut: false,
+		durationMs: Date.now() - started
+	};
+}
+function connOf(entry) {
+	return {
+		host: entry.host,
+		port: entry.port,
+		path: "/wsman",
+		username: entry.user,
+		password: entry.auth.password ?? "",
+		useHttps: entry.transport === "https",
+		rejectUnauthorized: entry.rejectUnauthorized ?? true
+	};
+}
+async function testConnection(conn) {
+	const started = Date.now();
+	try {
+		const result = await runScript(conn, "Write-Output ok", { timeoutMs: 3e4 });
+		return {
+			ok: result.exitCode === 0 && result.stdout.trim() !== "",
+			latencyMs: Date.now() - started
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			latencyMs: Date.now() - started,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+const TRANSFER_CHUNK = 48 * 1024;
+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;
+}
+async function downloadChunks(conn, remotePath, onChunk, onProgress, timeoutMs = 6e4) {
+	const total = await remoteFileSize(conn, remotePath, timeoutMs);
+	if (total === 0) return 0;
+	let offset = 0;
+	for (;;) {
+		const b64 = (await runScript(conn, psReadChunk(remotePath, offset, TRANSFER_CHUNK), { timeoutMs })).stdout.trim();
+		const bytes = Buffer.from(b64, "base64").length;
+		if (bytes === 0) break;
+		onChunk(b64, bytes);
+		offset += bytes;
+		onProgress?.(offset, total);
+		if (offset >= total || bytes < 49152) break;
+	}
+	return offset;
+}
+async function uploadBuffer(conn, remotePath, data, onProgress, timeoutMs = 6e4) {
+	let written = 0;
+	let first = true;
+	for (let offset = 0; offset < data.length; offset += TRANSFER_CHUNK) {
+		const chunk = data.subarray(offset, Math.min(offset + TRANSFER_CHUNK, data.length));
+		await runScript(conn, psWriteChunk(remotePath, chunk.toString("base64"), !first), { timeoutMs });
+		written += chunk.length;
+		first = false;
+		onProgress?.(written, data.length);
+	}
+	return written;
+}
+//#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.
+*/
+/**
+* Convert a Windows drive path to its UNC admin-share form.
+* D:\\dir\\file -> \\\\host\\D$\\dir\\file
+*/
+function adminSharePath(host, remotePath) {
+	const absolute = remotePath.replace(/[\\/]+$/, "");
+	const match = /^([A-Za-z]):[\\/](.*)$/.exec(absolute);
+	if (match === null) throw new Error("SMB requires an absolute remote path like D:\\dir\\file");
+	const drive = match[1];
+	const tail = match[2];
+	return "\\\\" + host + "\\" + drive + "$" + (tail === "" ? "" : "\\" + tail);
+}
+/** Run one cmd.exe process; returns output and exit code. */
+function runCmd(args, input, timeoutMs = 6e4) {
+	return new Promise((resolve) => {
+		const child = spawn("cmd.exe", ["/c", ...args], {
+			windowsHide: true,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const stdout = [];
+		const stderr = [];
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			try {
+				child.kill();
+			} catch {}
+			settled = true;
+			resolve({
+				code: 1,
+				stdout: "",
+				stderr: "SMB net use timed out"
+			});
+		}, timeoutMs);
+		child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
+		child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
+		child.on("error", (error) => {
+			if (settled) return;
+			clearTimeout(timer);
+			settled = true;
+			resolve({
+				code: 1,
+				stdout: "",
+				stderr: error instanceof Error ? error.message : String(error)
+			});
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			clearTimeout(timer);
+			settled = true;
+			resolve({
+				code: code ?? 1,
+				stdout: Buffer.concat(stdout).toString("utf8"),
+				stderr: Buffer.concat(stderr).toString("utf8")
+			});
+		});
+		if (input !== void 0) child.stdin.end(input);
+		else child.stdin.end();
+	});
+}
+/** SHA-256 of a local file. */
+async function sha256File(localPath) {
+	return createHash("sha256").update(await readFile(localPath)).digest("hex").toUpperCase();
+}
+/** SHA-256 of a remote file through the UNC path. */
+async function remoteSha256(host, remotePath) {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { stdout } = await promisify(execFile)("certutil.exe", [
+		"-hashfile",
+		adminSharePath(host, remotePath),
+		"SHA256"
+	]);
+	const match = /([0-9A-Fa-f]{64})/.exec(stdout);
+	if (match === null) throw new Error("SMB remote hash verification failed: " + stdout);
+	return match[1].toUpperCase();
+}
+/**
+* Copy one local file to a remote Windows host over SMB, verifying the
+* remote SHA-256 matches the local source.
+*/
+async function uploadSmb(entry, localPath, remotePath, timeoutMs = 3e5) {
+	const unc = adminSharePath(entry.host, remotePath);
+	const mount = await runCmd([
+		"net",
+		"use",
+		"\\\\" + entry.host + "\\IPC$",
+		entry.auth.password ?? "",
+		"/user:" + entry.user
+	], void 0, timeoutMs);
+	if (mount.code !== 0) throw new Error("SMB net use failed: " + (mount.stderr || mount.stdout));
+	try {
+		const { mkdir } = await import("node:fs/promises");
+		const { dirname } = await import("node:path");
+		await mkdir(dirname(unc), { recursive: true });
+		await copyFile(localPath, unc);
+		const local = await stat(localPath);
+		const localHash = await sha256File(localPath);
+		const remoteHash = await remoteSha256(entry.host, remotePath);
+		if (remoteHash !== localHash) throw new Error("SMB upload hash mismatch: local " + localHash + ", remote " + remoteHash);
+		return {
+			bytes: local.size,
+			channel: "smb"
+		};
+	} finally {
+		await runCmd([
+			"net",
+			"use",
+			"\\\\" + entry.host + "\\IPC$",
+			"/delete",
+			"/y"
+		], void 0, 3e4);
+	}
+}
+/**
+* Copy one remote Windows file to a local path over SMB and verify the local
+* SHA-256 matches the remote source.
+*/
+async function downloadSmb(entry, remotePath, localPath, timeoutMs = 3e5) {
+	const unc = adminSharePath(entry.host, remotePath);
+	const mount = await runCmd([
+		"net",
+		"use",
+		"\\\\" + entry.host + "\\IPC$",
+		entry.auth.password ?? "",
+		"/user:" + entry.user
+	], void 0, timeoutMs);
+	if (mount.code !== 0) throw new Error("SMB net use failed: " + (mount.stderr || mount.stdout));
+	try {
+		await copyFile(unc, localPath);
+		const local = await stat(localPath);
+		const localHash = await sha256File(localPath);
+		const remoteHash = await remoteSha256(entry.host, remotePath);
+		if (remoteHash !== localHash) throw new Error("SMB download hash mismatch: remote " + remoteHash + ", local " + localHash);
+		return {
+			bytes: local.size,
+			channel: "smb"
+		};
+	} finally {
+		await runCmd([
+			"net",
+			"use",
+			"\\\\" + entry.host + "\\IPC$",
+			"/delete",
+			"/y"
+		], void 0, 3e4);
+	}
+}
+//#endregion
+//#region src/engine/console.ts
+var ConsoleSession = class {
+	conn;
+	running = false;
+	exited = false;
+	queue = Promise.resolve();
+	onData;
+	onExit;
+	constructor(conn) {
+		this.conn = conn;
+	}
+	async start() {
+		this.running = true;
+	}
+	send(data) {
+		const command = data.replace(/\r?\n/g, "").trim();
+		if (!this.running || command === "") return;
+		if (command.toLowerCase() === "exit") {
+			this.close();
+			return;
+		}
+		this.queue = this.queue.then(async () => {
+			if (!this.running) return;
+			try {
+				const result = await runScript(this.conn, command, { timeoutMs: 12e4 });
+				if (result.stdout !== "") this.onData?.(result.stdout + (result.stdout.endsWith("\n") ? "" : "\n"));
+				if (result.stderr !== "") this.onData?.(result.stderr + (result.stderr.endsWith("\n") ? "" : "\n"));
+				if (result.timedOut) this.onData?.("[timed out]\n");
+			} catch (error) {
+				this.onData?.("[error] " + (error instanceof Error ? error.message : String(error)) + "\n");
+			}
+		});
+	}
+	close() {
+		if (!this.running) return;
+		this.running = false;
+		this.exited = true;
+	}
+	finish(code, error) {
+		if (this.exited) return;
+		this.exited = true;
+		this.running = false;
+		this.onExit?.(code, error);
+	}
+};
+//#endregion
+//#region src/engine.ts
+/** JSON-safe parse of the envelope output into a typed value. */
+function parseJson(text) {
+	const trimmed = text.trim();
+	if (trimmed === "" || trimmed === "null") return [];
+	return JSON.parse(trimmed);
+}
+/** A tiny per-alias in-flight limiter so GUI bursts do not pile up sockets. */
+var AliasGate = class {
+	queues = /* @__PURE__ */ new Map();
+	async run(alias, fn) {
+		const next = (this.queues.get(alias) ?? Promise.resolve()).then(() => fn(), () => fn());
+		this.queues.set(alias, next.then(() => void 0, () => void 0));
+		try {
+			return await next;
+		} finally {
+			if (this.queues.get(alias) === next.then(() => void 0, () => void 0)) {}
+		}
+	}
+};
+/** The engine. One instance per plugin apply; dispose() clears nothing pooled (WinRM is per-call HTTP). */
+var WinRmEngine = class {
+	store;
+	gate = new AliasGate();
+	constructor(store) {
+		this.store = store;
+	}
+	/** Secret-free host list (filtered by the optional query). */
+	list(query) {
+		const needle = query?.trim().toLowerCase();
+		return this.store.list().filter((entry) => needle === void 0 || needle === "" || entry.alias.toLowerCase().includes(needle) || (entry.description ?? "").toLowerCase().includes(needle) || entry.host.toLowerCase().includes(needle) || entry.tags.some((tag) => tag.toLowerCase().includes(needle))).map((entry) => this.store.summarize(entry));
+	}
+	/** One host summary by alias. */
+	find(alias) {
+		const entry = this.store.find(alias);
+		return entry === void 0 ? void 0 : this.store.summarize(entry);
+	}
+	/** Run one PowerShell command on `alias`. */
+	async exec(alias, command, timeoutMs) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) return {
+			success: false,
+			exitCode: null,
+			timedOut: false,
+			stdout: "",
+			stderr: "",
+			durationMs: 0,
+			error: `alias '${alias}' not found`
+		};
+		return this.gate.run(alias, async () => {
+			try {
+				const result = await runScript(connOf(entry), command, { timeoutMs: timeoutMs ?? 6e4 });
+				return {
+					success: result.exitCode === 0,
+					exitCode: result.exitCode,
+					timedOut: result.timedOut,
+					stdout: result.stdout,
+					stderr: result.stderr,
+					durationMs: result.durationMs
+				};
+			} catch (error) {
+				return {
+					success: false,
+					exitCode: null,
+					timedOut: false,
+					stdout: "",
+					stderr: "",
+					durationMs: 0,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		});
+	}
+	/** Run one command against many hosts concurrently. */
+	async cluster(options) {
+		let matched = this.store.list();
+		if (options.aliases !== void 0 && options.aliases.length > 0) {
+			const set = new Set(options.aliases);
+			matched = matched.filter((entry) => set.has(entry.alias));
+		}
+		if (options.environment !== void 0 && options.environment !== "") matched = matched.filter((entry) => entry.environment === options.environment);
+		if (options.tags !== void 0 && options.tags.length > 0) matched = matched.filter((entry) => options.tags.every((tag) => entry.tags.includes(tag)));
+		const maxWorkers = Math.max(1, Math.min(options.maxWorkers ?? 8, 32));
+		const results = [];
+		let cursor = 0;
+		const worker = async () => {
+			for (;;) {
+				const index = cursor++;
+				const entry = matched[index];
+				if (entry === void 0) return;
+				const outcome = await this.exec(entry.alias, options.command, options.timeoutMs);
+				results.push({
+					alias: entry.alias,
+					ok: outcome.success,
+					exitCode: outcome.exitCode,
+					timedOut: outcome.timedOut,
+					stdout: outcome.stdout,
+					stderr: outcome.stderr,
+					durationMs: outcome.durationMs,
+					...outcome.error !== void 0 ? { error: outcome.error } : {}
+				});
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(maxWorkers, matched.length) }, () => worker()));
+		return results;
+	}
+	/** Full service table. */
+	async listServices(alias) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psListServices(), { timeoutMs: 6e4 });
+			if (result.exitCode !== 0) throw new Error(result.stdout || "failed to list services");
+			return parseJson(result.stdout).map((item) => ({
+				name: item.name ?? "",
+				displayName: item.displayName ?? "",
+				status: item.status ?? "",
+				startMode: item.startMode ?? "",
+				startName: item.startName ?? ""
+			}));
+		});
+	}
+	/** One service action, returning the refreshed service row. */
+	async serviceAction(alias, name, action) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psServiceAction(name, action), { timeoutMs: 6e4 });
+			if (result.exitCode !== 0) throw new Error(result.stdout || `service action '${action}' failed`);
+			const item = parseJson(result.stdout)[0] ?? {};
+			return {
+				name: item.name ?? name,
+				displayName: item.displayName ?? "",
+				status: item.status ?? "",
+				startMode: item.startMode ?? "",
+				startName: item.startName ?? ""
+			};
+		});
+	}
+	/** Full process table. */
+	async listProcesses(alias) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psListProcesses(), { timeoutMs: 6e4 });
+			if (result.exitCode !== 0) throw new Error(result.stdout || "failed to list processes");
+			return parseJson(result.stdout).map((item) => ({
+				id: item.id ?? 0,
+				name: item.name ?? "",
+				...item.cpu !== void 0 && item.cpu !== null ? { cpu: item.cpu } : {},
+				...item.memMB !== void 0 && item.memMB !== null ? { memMB: item.memMB } : {},
+				...item.startTime !== void 0 && item.startTime !== null ? { startTime: item.startTime } : {},
+				...item.path !== void 0 && item.path !== null ? { path: item.path } : {}
+			}));
+		});
+	}
+	/** Kill one process by id. */
+	async killProcess(alias, id) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psKillProcess(id), { timeoutMs: 3e4 });
+			if (result.exitCode !== 0) throw new Error(result.stdout || "failed to kill process");
+		});
+	}
+	/** List a remote directory. */
+	async ls(alias, dir) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psListDir(dir), { timeoutMs: 6e4 });
+			if (result.exitCode !== 0) throw new Error(result.stdout || `failed to list '${dir}'`);
+			return parseJson(result.stdout).map((item) => ({
+				name: item.name ?? "",
+				type: item.type === "dir" || item.type === "file" ? item.type : "other",
+				size: item.size ?? 0,
+				mtimeMs: item.mtimeMs ?? 0
+			}));
+		});
+	}
+	/** Upload one local file to a remote path. Defaults to SMB with WinRM fallback. */
+	async upload(alias, localPath, remotePath, onProgress, channel = "auto") {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		const { readFileSync } = await import("node:fs");
+		const data = readFileSync(localPath);
+		return this.gate.run(alias, async () => {
+			onProgress?.({
+				phase: "connecting",
+				file: remotePath,
+				transferred: 0,
+				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
+				});
+			}
+			const bytes = await uploadBuffer(connOf(entry), remotePath, data, (transferred, total) => {
+				onProgress?.({
+					phase: "transferring",
+					file: remotePath,
+					transferred,
+					total,
+					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0
+				});
+			});
+			onProgress?.({
+				phase: "done",
+				file: remotePath,
+				transferred: bytes,
+				total: bytes,
+				percent: 100
+			});
+			return {
+				bytes,
+				channel: "winrm"
+			};
+		});
+	}
+	/** Download one remote file to a local path. Defaults to SMB with WinRM fallback. */
+	async download(alias, remotePath, localPath, onProgress, channel = "auto") {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			onProgress?.({
+				phase: "connecting",
+				file: remotePath,
+				transferred: 0,
+				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
+				});
+			}
+			const { createWriteStream } = await import("node:fs");
+			const sink = createWriteStream(localPath, { mode: 384 });
+			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?.({
+					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);
+				});
+			});
+			onProgress?.({
+				phase: "done",
+				file: remotePath,
+				transferred: bytes,
+				total: bytes,
+				percent: 100
+			});
+			return {
+				bytes,
+				channel: "winrm"
+			};
+		});
+	}
+	/** Open a streaming PowerShell console session (standalone connection). */
+	async openConsole(alias) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		const session = new ConsoleSession(connOf(entry));
+		await session.start();
+		return session;
+	}
+	/** Probe connectivity. */
+	async test(alias) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) return {
+			ok: false,
+			error: `alias '${alias}' not found`
+		};
+		return this.gate.run(alias, async () => {
+			return await testConnection(connOf(entry));
+		});
+	}
+	/** No pooled resources to close (WinRM is per-call HTTP). */
+	dispose() {}
+};
+//#endregion
+//#region src/loopback.ts
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+function isIPv4Loopback(v4) {
+	const parts = v4.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+function isLoopbackAddress(address) {
+	if (address === void 0) return false;
+	const normalized = address.toLowerCase();
+	if (normalized === "::1") return true;
+	if (normalized.startsWith("::ffff:")) return isIPv4Loopback(normalized.slice(7));
+	return isIPv4Loopback(normalized);
+}
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	return isIPv4Loopback(hostname);
+}
+/**
+* Request-level trust fence: a loopback socket address AND a loopback Host
+* header, plus browser same-origin markers. The socket address is
+* authoritative; X-Forwarded-For is never trusted.
+*/
+function isLoopbackRequest(request) {
+	if (!isLoopbackAddress(request.socket.remoteAddress)) return false;
+	const host = request.headers.host;
+	if (typeof host !== "string") return false;
+	let hostUrl;
+	try {
+		hostUrl = new URL("http://" + host);
+	} catch {
+		return false;
+	}
+	if (!isLoopbackHostname(hostUrl.hostname)) return false;
+	if (request.headers["sec-fetch-site"] === "cross-site") return false;
+	const origin = request.headers.origin;
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/protocol.ts
+const WINRM_API = {
+	hosts: "/api/dsh-winrm/hosts",
+	test: "/api/dsh-winrm/test",
+	exec: "/api/dsh-winrm/exec",
+	cluster: "/api/dsh-winrm/cluster",
+	services: "/api/dsh-winrm/services",
+	processes: "/api/dsh-winrm/processes",
+	ls: "/api/dsh-winrm/ls",
+	upload: "/api/dsh-winrm/upload",
+	download: "/api/dsh-winrm/download",
+	console: "/api/dsh-winrm/console"
+};
+//#endregion
+//#region src/routes.ts
+/**
+* The /api/dsh-winrm route family: host CRUD, exec, cluster, services,
+* processes, remote listing, NDJSON upload progress, binary download, and
+* the WebSocket PowerShell console upgrade. Every route carries a
+* loopback-only trust fence (plus browser same-origin markers) — these
+* endpoints execute commands on remote machines, so LAN-exposed dsh web
+* deployments must not serve them.
+*/
+/** Cap on JSON request bodies. */
+const MAX_JSON_BODY_BYTES = 64 * 1024;
+/** Cap on declared upload bodies (staged to disk before chunking out). */
+const MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024;
+/** One noServer WebSocket server for console upgrades. */
+const consoleWss = new WebSocketServer({ noServer: true });
+/** One JSON response. */
+function writeJson(res, status, body) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"referrer-policy": "no-referrer"
+	});
+	res.end(payload);
+}
+/** Read a JSON request body (undefined when too large or unparseable). */
+async function readJsonBody(req) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const buffer = chunk;
+		size += buffer.length;
+		if (size > MAX_JSON_BODY_BYTES) return void 0;
+		chunks.push(buffer);
+	}
+	try {
+		const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** URL query helper (first value, decoded). */
+function queryParam(url, name) {
+	const value = url.searchParams.get(name);
+	return value === null ? void 0 : value;
+}
+/**
+* Build every /api/dsh-winrm route plus the console upgrade.
+* @param deps - store, engine, staging dir.
+*/
+function makeRoutes(deps) {
+	const { store, engine } = deps;
+	const staging = deps.stagingDir ?? join(tmpdir(), "dsh-winrm-uploads");
+	const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES;
+	mkdirSync(staging, {
+		recursive: true,
+		mode: 448
+	});
+	/** Guard helper: fence + method check. */
+	const guard = (req, res, method) => {
+		if (!isLoopbackRequest(req)) {
+			writeJson(res, 403, { error: "forbidden: loopback-only" });
+			return false;
+		}
+		if (req.method !== method) {
+			writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+			return false;
+		}
+		return true;
+	};
+	return {
+		routes: [
+			{
+				kind: "exact",
+				path: WINRM_API.hosts,
+				handler: async (req, res) => {
+					const method = req.method ?? "GET";
+					if (!isLoopbackRequest(req)) {
+						writeJson(res, 403, { error: "forbidden: loopback-only" });
+						return;
+					}
+					const url = new URL(req.url ?? "/", "http://localhost");
+					if (method === "GET") {
+						writeJson(res, 200, { hosts: engine.list(queryParam(url, "query")) });
+						return;
+					}
+					if (method === "POST") {
+						const body = await readJsonBody(req);
+						if (body === void 0) {
+							writeJson(res, 400, { error: "invalid JSON body" });
+							return;
+						}
+						try {
+							const entry = store.create(body);
+							writeJson(res, 201, { host: store.summarize(entry) });
+						} catch (error) {
+							writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+						}
+						return;
+					}
+					if (method !== "PATCH" && method !== "DELETE") {
+						writeJson(res, 405, { error: `method not allowed: ${method}` });
+						return;
+					}
+					const alias = queryParam(url, "alias");
+					if (alias === void 0 || alias === "") {
+						writeJson(res, 400, { error: "alias query parameter is required" });
+						return;
+					}
+					if (method === "PATCH") {
+						const body = await readJsonBody(req);
+						if (body === void 0) {
+							writeJson(res, 400, { error: "invalid JSON body" });
+							return;
+						}
+						try {
+							const entry = store.update(alias, body);
+							writeJson(res, 200, { host: store.summarize(entry) });
+						} catch (error) {
+							writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+						}
+						return;
+					}
+					if (method === "DELETE") {
+						try {
+							store.delete(alias);
+							writeJson(res, 200, { ok: true });
+						} catch (error) {
+							writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+						}
+						return;
+					}
+					writeJson(res, 405, { error: `method not allowed: ${method}` });
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.test,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const body = await readJsonBody(req);
+					const alias = typeof body?.alias === "string" ? body.alias : "";
+					if (alias === "") {
+						writeJson(res, 400, { error: "alias is required" });
+						return;
+					}
+					try {
+						writeJson(res, 200, { result: await engine.test(alias) });
+					} catch (error) {
+						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.exec,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const body = await readJsonBody(req);
+					const alias = typeof body?.alias === "string" ? body.alias : "";
+					const command = typeof body?.command === "string" ? body.command : "";
+					if (alias === "" || command === "") {
+						writeJson(res, 400, { error: "alias and command are required" });
+						return;
+					}
+					const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
+					try {
+						writeJson(res, 200, { result: await engine.exec(alias, command, timeoutMs) });
+					} catch (error) {
+						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.cluster,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const body = await readJsonBody(req);
+					const command = typeof body?.command === "string" ? body.command : "";
+					if (command === "") {
+						writeJson(res, 400, { error: "command is required" });
+						return;
+					}
+					const aliases = Array.isArray(body?.aliases) ? body.aliases.filter((x) => typeof x === "string") : void 0;
+					const tags = Array.isArray(body?.tags) ? body.tags.filter((x) => typeof x === "string") : void 0;
+					const environment = typeof body?.environment === "string" ? body.environment : void 0;
+					const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
+					const maxWorkers = typeof body?.maxWorkers === "number" ? body.maxWorkers : void 0;
+					try {
+						writeJson(res, 200, { results: await engine.cluster({
+							command,
+							aliases,
+							environment,
+							tags,
+							timeoutMs,
+							maxWorkers
+						}) });
+					} catch (error) {
+						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.services,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const body = await readJsonBody(req);
+					const alias = typeof body?.alias === "string" ? body.alias : "";
+					const name = typeof body?.name === "string" ? body.name : "";
+					const action = typeof body?.action === "string" ? body.action : "list";
+					if (alias === "") {
+						writeJson(res, 400, { error: "alias is required" });
+						return;
+					}
+					try {
+						if (action === "list" || name === "") writeJson(res, 200, { services: await engine.listServices(alias) });
+						else writeJson(res, 200, { service: await engine.serviceAction(alias, name, action) });
+					} catch (error) {
+						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.processes,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const body = await readJsonBody(req);
+					const alias = typeof body?.alias === "string" ? body.alias : "";
+					const action = typeof body?.action === "string" ? body.action : "list";
+					const id = typeof body?.id === "number" ? body.id : void 0;
+					if (alias === "") {
+						writeJson(res, 400, { error: "alias is required" });
+						return;
+					}
+					try {
+						if (action === "kill" && id !== void 0) {
+							await engine.killProcess(alias, id);
+							writeJson(res, 200, { killed: id });
+						} else writeJson(res, 200, { processes: await engine.listProcesses(alias) });
+					} catch (error) {
+						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.ls,
+				handler: async (req, res) => {
+					if (!guard(req, res, "GET")) return;
+					const url = new URL(req.url ?? "/", "http://localhost");
+					const alias = queryParam(url, "alias");
+					const dir = queryParam(url, "path") ?? "C:\\";
+					if (alias === void 0 || alias === "") {
+						writeJson(res, 400, { error: "alias query parameter is required" });
+						return;
+					}
+					try {
+						writeJson(res, 200, { entries: await engine.ls(alias, dir) });
+					} catch (error) {
+						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.upload,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const url = new URL(req.url ?? "/", "http://localhost");
+					const alias = queryParam(url, "alias");
+					const remotePath = queryParam(url, "remotePath");
+					if (alias === void 0 || remotePath === void 0) {
+						writeJson(res, 400, { error: "alias and remotePath query parameters are required" });
+						return;
+					}
+					const channel = queryParam(url, "channel") ?? "auto";
+					const declared = Number(req.headers["content-length"]);
+					if (Number.isFinite(declared) && declared > maxUploadBytes) {
+						writeJson(res, 413, { error: "upload body too large" });
+						return;
+					}
+					res.writeHead(200, {
+						"content-type": "application/x-ndjson; charset=utf-8",
+						"cache-control": "no-cache",
+						"referrer-policy": "no-referrer"
+					});
+					const emit = (line) => {
+						try {
+							res.write(JSON.stringify(line) + "\n");
+						} catch {}
+					};
+					const tmp = join(staging, `upload-${randomBytes(6).toString("hex")}`);
+					const sink = createWriteStream(tmp, { mode: 384 });
+					let settled = false;
+					const fail = (error) => {
+						if (settled) return;
+						settled = true;
+						emit({
+							type: "result",
+							ok: false,
+							error: error instanceof Error ? error.message : String(error)
+						});
+						const cleanup = () => {
+							unlink(tmp).catch(() => void 0).finally(() => {
+								try {
+									res.end();
+								} catch {}
+							});
+						};
+						if (sink.destroyed) cleanup();
+						else {
+							sink.once("close", cleanup);
+							try {
+								sink.destroy();
+							} catch {
+								cleanup();
+							}
+						}
+					};
+					const done = () => {
+						if (settled) return;
+						settled = true;
+						try {
+							res.end();
+						} catch {}
+					};
+					sink.on("error", (error) => fail(error));
+					req.on("error", (error) => fail(error));
+					req.on("aborted", () => fail("upload aborted by the client"));
+					res.on("error", () => fail("response stream closed"));
+					res.on("close", () => {
+						if (!res.writableEnded) fail("connection closed");
+					});
+					let received = 0;
+					let capped = false;
+					req.on("data", (chunk) => {
+						received += chunk.byteLength;
+						if (received > maxUploadBytes && !capped) {
+							capped = true;
+							fail("upload body too large");
+							res.on("finish", () => {
+								try {
+									req.destroy();
+								} catch {}
+							});
+							req.resume();
+						}
+					});
+					req.pipe(sink);
+					sink.on("finish", async () => {
+						if (settled) return;
+						emit({
+							type: "progress",
+							progress: {
+								phase: "connecting",
+								file: remotePath,
+								transferred: 0,
+								total: 0,
+								percent: 0
+							}
+						});
+						try {
+							const outcome = await engine.upload(alias, tmp, remotePath, (progress) => emit({
+								type: "progress",
+								progress
+							}), channel);
+							emit({
+								type: "result",
+								ok: true,
+								transferredBytes: outcome.bytes
+							});
+						} catch (error) {
+							emit({
+								type: "result",
+								ok: false,
+								error: error instanceof Error ? error.message : String(error)
+							});
+						} finally {
+							await unlink(tmp).catch(() => void 0);
+							done();
+						}
+					});
+				}
+			},
+			{
+				kind: "exact",
+				path: WINRM_API.download,
+				handler: async (req, res) => {
+					if (!guard(req, res, "GET")) return;
+					const url = new URL(req.url ?? "/", "http://localhost");
+					const alias = queryParam(url, "alias");
+					const remotePath = queryParam(url, "remotePath");
+					if (alias === void 0 || remotePath === void 0) {
+						writeJson(res, 400, { error: "alias and remotePath query parameters are required" });
+						return;
+					}
+					const channel = queryParam(url, "channel") ?? "auto";
+					const tmp = join(staging, `download-${randomBytes(6).toString("hex")}`);
+					try {
+						closeSync(openSync(tmp, "w", 384));
+						const outcome = await engine.download(alias, remotePath, tmp, void 0, channel);
+						res.writeHead(200, {
+							"content-type": "application/octet-stream",
+							"content-length": String(outcome.bytes),
+							"content-disposition": `attachment; filename="${basename(remotePath).replace(/"/g, "")}"`,
+							"referrer-policy": "no-referrer"
+						});
+						await new Promise((resolve, reject) => {
+							const source = createReadStream(tmp);
+							source.on("error", reject);
+							res.on("error", reject);
+							source.pipe(res);
+							source.on("end", resolve);
+						});
+					} catch (error) {
+						if (!res.headersSent) writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+						else res.destroy();
+					} finally {
+						await unlink(tmp).catch(() => void 0);
+					}
+				}
+			}
+		],
+		upgrade: {
+			path: WINRM_API.console,
+			handler: (req, socket, head) => {
+				if (!isLoopbackRequest(req)) {
+					socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+					socket.destroy();
+					return;
+				}
+				const alias = queryParam(new URL(req.url ?? "/", "http://localhost"), "alias");
+				if (alias === void 0) {
+					socket.write("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+					socket.destroy();
+					return;
+				}
+				consoleWss.handleUpgrade(req, socket, head, (ws) => {
+					let session;
+					let closed = false;
+					const sendFrame = (frame) => {
+						if (closed || ws.readyState !== WebSocket.OPEN) return;
+						ws.send(JSON.stringify(frame));
+					};
+					const closeSession = () => {
+						const opened = session;
+						session = void 0;
+						if (opened !== void 0) opened.close();
+					};
+					engine.openConsole(alias).then((opened) => {
+						if (ws.readyState !== WebSocket.OPEN) {
+							opened.close();
+							return;
+						}
+						session = opened;
+						sendFrame({
+							type: "ready",
+							alias
+						});
+						opened.onData = (data) => sendFrame({
+							type: "output",
+							data
+						});
+						opened.onExit = (code, error) => {
+							sendFrame({
+								type: "exit",
+								code,
+								error
+							});
+							closed = true;
+							try {
+								ws.close(1e3);
+							} catch {}
+						};
+					}).catch((error) => {
+						sendFrame({
+							type: "exit",
+							code: null,
+							error: error instanceof Error ? error.message : String(error)
+						});
+						closed = true;
+						try {
+							ws.close(1e3);
+						} catch {}
+					});
+					ws.on("message", (data) => {
+						let frame;
+						try {
+							frame = JSON.parse(String(data));
+						} catch {
+							return;
+						}
+						if (frame.type === "input") session?.send(frame.data);
+					});
+					ws.on("close", () => {
+						closed = true;
+						closeSession();
+					});
+					ws.on("error", () => {
+						closed = true;
+						closeSession();
+					});
+				});
+			}
+		}
+	};
+}
+//#endregion
+//#region src/store.ts
+/**
+* Host config store: one JSON file (~/.dsh/dsh-winrm.json) holding every
+* Windows host entry, written atomically (tmp + rename). Secrets (passwords)
+* live in this user-owned file in plaintext — the same trust model as
+* dsh-ssh; document it, never log it.
+*/
+/** File format version. */
+const FORMAT_VERSION = 1;
+/** Store file location: <home>/.dsh/dsh-winrm.json. */
+function storePath() {
+	return join(homedir(), ".dsh", "dsh-winrm.json");
+}
+/** Validate the wire shape of a host payload; returns a message or undefined. */
+function validateHostPayload(payload) {
+	if (typeof payload !== "object" || payload === null) return "body must be a JSON object";
+	const p = payload;
+	if (typeof p.host !== "string" || p.host.trim() === "") return "host is required";
+	if (typeof p.user !== "string" || p.user.trim() === "") return "user is required";
+	const auth = p.auth;
+	if (auth !== void 0) {
+		if (typeof auth !== "object" || auth === null) return "auth must be an object";
+		if (auth.kind !== "password") return "auth.kind must be password";
+		if (auth.password !== void 0 && typeof auth.password !== "string") return "auth.password must be a string when provided";
+	}
+	if (p.port !== void 0 && (typeof p.port !== "number" || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535)) return "port must be an integer in 1..65535";
+	if (p.transport !== void 0 && p.transport !== "http" && p.transport !== "https") return "transport must be http or https";
+	if (p.rejectUnauthorized !== void 0 && typeof p.rejectUnauthorized !== "boolean") return "rejectUnauthorized must be a boolean";
+	if (p.tags !== void 0 && (!Array.isArray(p.tags) || p.tags.some((x) => typeof x !== "string"))) return "tags must be an array of strings";
+}
+/** Alias grammar: letters/digits plus dots, hyphens, underscores (IP/domain aliases included). */
+const ALIAS_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** Validate an alias for creation. */
+function validateAlias(alias) {
+	if (!ALIAS_RE.test(alias)) return "alias must be letters, digits, dots, hyphens or underscores";
+}
+/**
+* The host store. Pure file I/O — no cordis dependency, unit-testable.
+*/
+var HostStore = class {
+	/** The JSON file path. */
+	path;
+	/**
+	* @param path - store file path (defaults to the standard location).
+	*/
+	constructor(path) {
+		this.path = resolve(path ?? storePath());
+	}
+	/** Load all entries (empty store when the file is absent). */
+	list() {
+		return this.load().hosts;
+	}
+	/** Find one entry by alias. */
+	find(alias) {
+		return this.list().find((entry) => entry.alias === alias);
+	}
+	/** Secret-free projection for the browser and agent surfaces. */
+	summarize(entry) {
+		return {
+			alias: entry.alias,
+			host: entry.host,
+			port: entry.port,
+			user: entry.user,
+			auth: entry.auth.kind,
+			transport: entry.transport,
+			...entry.rejectUnauthorized !== void 0 ? { rejectUnauthorized: entry.rejectUnauthorized } : {},
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.environment !== void 0 ? { environment: entry.environment } : {},
+			tags: [...entry.tags],
+			...entry.location !== void 0 ? { location: entry.location } : {},
+			createdAt: entry.createdAt,
+			updatedAt: entry.updatedAt
+		};
+	}
+	/** Create one entry. Throws on alias collision or invalid payload. */
+	create(payload) {
+		const alias = payload.alias?.trim();
+		if (!alias) throw new Error("alias is required");
+		const aliasError = validateAlias(alias);
+		if (aliasError !== void 0) throw new Error(aliasError);
+		const bodyError = validateHostPayload(payload);
+		if (bodyError !== void 0) throw new Error(bodyError);
+		if (payload.auth === void 0) throw new Error("auth is required");
+		const file = this.load();
+		if (file.hosts.some((entry) => entry.alias === alias)) throw new Error(`alias '${alias}' already exists`);
+		const now = Date.now();
+		const entry = {
+			alias,
+			host: payload.host.trim(),
+			port: payload.port ?? 5985,
+			user: payload.user.trim(),
+			auth: {
+				kind: "password",
+				password: payload.auth.password
+			},
+			transport: payload.transport ?? "http",
+			...payload.rejectUnauthorized !== void 0 ? { rejectUnauthorized: payload.rejectUnauthorized } : {},
+			description: payload.description?.trim() || void 0,
+			environment: payload.environment?.trim() || void 0,
+			tags: [...payload.tags ?? []].map((tag) => tag.trim()).filter((tag) => tag !== ""),
+			location: payload.location?.trim() || void 0,
+			createdAt: now,
+			updatedAt: now
+		};
+		file.hosts.push(entry);
+		this.save(file);
+		return entry;
+	}
+	/** Update the fields present in `patch`; unknown aliases throw. */
+	update(alias, patch) {
+		const file = this.load();
+		const entry = file.hosts.find((candidate) => candidate.alias === alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		if (patch.host !== void 0 && (typeof patch.host !== "string" || patch.host.trim() === "")) throw new Error("host is required");
+		if (patch.user !== void 0 && (typeof patch.user !== "string" || patch.user.trim() === "")) throw new Error("user is required");
+		if (patch.port !== void 0 && (typeof patch.port !== "number" || !Number.isInteger(patch.port) || patch.port < 1 || patch.port > 65535)) throw new Error("port must be an integer in 1..65535");
+		if (patch.transport !== void 0 && patch.transport !== "http" && patch.transport !== "https") throw new Error("transport must be http or https");
+		if (patch.tags !== void 0 && (!Array.isArray(patch.tags) || patch.tags.some((x) => typeof x !== "string"))) throw new Error("tags must be an array of strings");
+		if (patch.host !== void 0) entry.host = patch.host.trim();
+		if (patch.port !== void 0) entry.port = patch.port;
+		if (patch.user !== void 0) entry.user = patch.user.trim();
+		if (patch.auth !== void 0) {
+			const auth = patch.auth;
+			if (auth.kind !== "password") throw new Error("auth.kind must be password");
+			entry.auth = {
+				kind: "password",
+				password: auth.password
+			};
+		}
+		if (patch.transport !== void 0) entry.transport = patch.transport;
+		if (patch.rejectUnauthorized !== void 0) entry.rejectUnauthorized = patch.rejectUnauthorized;
+		if (patch.description !== void 0) entry.description = patch.description.trim() || void 0;
+		if (patch.environment !== void 0) entry.environment = patch.environment.trim() || void 0;
+		if (patch.tags !== void 0) entry.tags = [...patch.tags].map((tag) => tag.trim()).filter((tag) => tag !== "");
+		if (patch.location !== void 0) entry.location = patch.location.trim() || void 0;
+		entry.updatedAt = Date.now();
+		this.save(file);
+		return entry;
+	}
+	/** Remove one entry. */
+	delete(alias) {
+		const file = this.load();
+		const index = file.hosts.findIndex((candidate) => candidate.alias === alias);
+		if (index < 0) throw new Error(`alias '${alias}' not found`);
+		file.hosts.splice(index, 1);
+		this.save(file);
+	}
+	/**
+	* Last parsed store keyed by file identity. list/find ride every acquire
+	* and GUI refresh; re-reading and re-parsing the whole file each call is
+	* wasted work when the file has not changed. Any save invalidates.
+	*/
+	cache;
+	load() {
+		let stats;
+		try {
+			stats = statSync(this.path);
+		} catch {
+			this.cache = void 0;
+			return {
+				version: FORMAT_VERSION,
+				hosts: []
+			};
+		}
+		if (this.cache !== void 0 && this.cache.mtimeMs === stats.mtimeMs && this.cache.size === stats.size) return this.cache.file;
+		try {
+			const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+			if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.hosts)) throw new Error("store file shape invalid");
+			this.cache = {
+				mtimeMs: stats.mtimeMs,
+				size: stats.size,
+				file: parsed
+			};
+			return parsed;
+		} catch {
+			this.cache = void 0;
+			try {
+				renameSync(this.path, `${this.path}.corrupt-${Date.now()}`);
+			} catch {}
+			return {
+				version: FORMAT_VERSION,
+				hosts: []
+			};
+		}
+	}
+	save(file) {
+		const dir = dirname(this.path);
+		if (!existsSync(dir)) mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const tmp = this.path + ".tmp";
+		writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n", {
+			encoding: "utf8",
+			mode: 384
+		});
+		renameSync(tmp, this.path);
+		this.cache = void 0;
+	}
+};
+//#endregion
+//#region src/tools.ts
+/**
+* Agent tools: the DSH-native counterpart of the GUI — every tool talks to
+* the same engine the web UI uses, so a host configured in the GUI is
+* immediately operable by any agent, and vice versa.
+*/
+/** One text content block (the only render shape these tools emit). */
+function text(value) {
+	return [{
+		type: "text",
+		text: value
+	}];
+}
+/** Host table render shared by list surfaces. */
+function renderHosts(hosts) {
+	if (hosts.length === 0) return "no hosts configured";
+	return [
+		"alias | host | port | user | transport | environment | tags | description",
+		"--- | --- | --- | --- | --- | --- | --- | ---",
+		...hosts.map((host) => [
+			host.alias,
+			host.host,
+			String(host.port),
+			host.user,
+			host.transport,
+			host.environment ?? "-",
+			host.tags.length > 0 ? host.tags.join(",") : "-",
+			host.description ?? ""
+		].join(" | "))
+	].join("\n");
+}
+/** Render one exec result (mirrors the bash-tool exit-code convention). */
+function renderExec(result) {
+	const parts = [result.timedOut ? "[timed out]" : `[exit code: ${result.exitCode ?? "null"}]`];
+	if (result.stdout !== "") parts.push("stdout:\n" + result.stdout);
+	if (result.stderr !== "") parts.push("stderr:\n" + result.stderr);
+	if (result.error !== void 0) parts.push("error: " + result.error);
+	parts.push(`duration: ${result.durationMs} ms`);
+	return parts.join("\n");
+}
+/** Render cluster outcomes compactly. */
+function renderCluster(results) {
+	if (results.length === 0) return "no hosts matched";
+	return results.map((result) => {
+		const status = result.ok ? "ok" : result.timedOut === true ? "timed out" : "failed";
+		const tail = result.error !== void 0 ? " (" + result.error + ")" : "";
+		return `${result.alias}: ${status} [exit code: ${result.exitCode ?? "null"}]${tail}`;
+	}).join("\n");
+}
+/** The host-list tool. */
+function winrmListTool(engine) {
+	return defineTool({
+		name: "winrm_list",
+		description: "List configured Windows hosts (alias, host, port, user, transport, environment, tags, description). Use winrm_exec etc. with the alias. Triggers: Windows server, WinRM, PowerShell remote, check server/status, deploy to Windows.",
+		parameters: { query: {
+			type: "string",
+			description: "Optional fuzzy match against alias, description, host, and tags."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { hosts: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							alias: {
+								type: "string",
+								required: true
+							},
+							host: {
+								type: "string",
+								required: true
+							},
+							port: {
+								type: "integer",
+								required: true
+							},
+							user: {
+								type: "string",
+								required: true
+							},
+							auth: {
+								type: "string",
+								enum: ["password"],
+								required: true
+							},
+							transport: {
+								type: "string",
+								enum: ["http", "https"],
+								required: true
+							},
+							description: { type: "string" },
+							environment: { type: "string" },
+							tags: {
+								type: "array",
+								items: { type: "string" },
+								required: true
+							},
+							location: { type: "string" },
+							createdAt: {
+								type: "integer",
+								required: true
+							},
+							updatedAt: {
+								type: "integer",
+								required: true
+							}
+						}
+					}
+				} }
+			},
+			render: (_args, value) => text(renderHosts(value.hosts ?? []))
+		},
+		async execute(args) {
+			return { hosts: engine.list(args.query) };
+		}
+	});
+}
+/** The command-execution tool (PowerShell). */
+function winrmExecTool(engine) {
+	return defineTool({
+		name: "winrm_exec",
+		description: "Execute a PowerShell command on a configured Windows host by alias. The command runs under PowerShell with UTF-8 output; prefer combining independent read-only queries into one command. Triggers: run command on Windows server, PowerShell remote, check server/status, service control, view logs, any remote Windows operation.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			command: {
+				type: "string",
+				required: true,
+				description: "The PowerShell command to run remotely (script body, no powershell.exe wrapper needed)."
+			},
+			timeoutMs: {
+				type: "integer",
+				description: "Timeout in milliseconds (default 60000)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					exitCode: {
+						oneOf: [{ type: "integer" }, { type: "null" }],
+						required: true
+					},
+					timedOut: {
+						type: "boolean",
+						required: true
+					},
+					stdout: {
+						type: "string",
+						required: true
+					},
+					stderr: {
+						type: "string",
+						required: true
+					},
+					durationMs: {
+						type: "integer",
+						required: true
+					},
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(renderExec(value))
+		},
+		async execute(args) {
+			return engine.exec(args.alias, args.command, args.timeoutMs);
+		}
+	});
+}
+/** The service-management tool. */
+function winrmServiceTool(engine) {
+	return defineTool({
+		name: "winrm_service",
+		description: "Manage Windows services on a configured host: list all services, or start/stop/restart one and change its startup type. Triggers: service control, start/stop/restart Windows service, check service status, set service startup type.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			name: {
+				type: "string",
+				description: "Service name (required for actions; omitted lists all services)."
+			},
+			action: {
+				type: "string",
+				enum: [
+					"list",
+					"start",
+					"stop",
+					"restart",
+					"set-auto",
+					"set-manual",
+					"set-disabled"
+				],
+				description: "list (default) / start / stop / restart / set-auto / set-manual / set-disabled."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					services: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								name: {
+									type: "string",
+									required: true
+								},
+								displayName: {
+									type: "string",
+									required: true
+								},
+								status: {
+									type: "string",
+									required: true
+								},
+								startMode: {
+									type: "string",
+									required: true
+								},
+								startName: { type: "string" }
+							}
+						}
+					},
+					service: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							name: {
+								type: "string",
+								required: true
+							},
+							displayName: {
+								type: "string",
+								required: true
+							},
+							status: {
+								type: "string",
+								required: true
+							},
+							startMode: {
+								type: "string",
+								required: true
+							},
+							startName: { type: "string" }
+						}
+					},
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => {
+				if (value.error !== void 0) return text("service error: " + value.error);
+				if (value.services !== void 0) {
+					if (value.services.length === 0) return text("no services");
+					return text([
+						"name | displayName | status | startMode",
+						"--- | --- | --- | ---",
+						...value.services.map((s) => `${s.name} | ${s.displayName} | ${s.status} | ${s.startMode}`)
+					].join("\n"));
+				}
+				if (value.service !== void 0) {
+					const s = value.service;
+					return text(`service ${s.name}: ${s.status} (startMode ${s.startMode}, displayName ${s.displayName})`);
+				}
+				return text("no result");
+			}
+		},
+		async execute(args) {
+			try {
+				if (args.name === void 0 || args.action === void 0 || args.action === "list") return { services: await engine.listServices(args.alias) };
+				return { service: await engine.serviceAction(args.alias, args.name, args.action) };
+			} catch (error) {
+				return { error: error instanceof Error ? error.message : String(error) };
+			}
+		}
+	});
+}
+/** The process-management tool. */
+function winrmProcessTool(engine) {
+	return defineTool({
+		name: "winrm_process",
+		description: "Manage processes on a configured Windows host: list all processes, or kill one by id. Triggers: process list, kill process, check what is running on a Windows server.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			id: {
+				type: "integer",
+				description: "Process id (required for kill; omitted lists processes)."
+			},
+			action: {
+				type: "string",
+				enum: ["list", "kill"],
+				description: "list (default) / kill."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					processes: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								id: {
+									type: "integer",
+									required: true
+								},
+								name: {
+									type: "string",
+									required: true
+								},
+								cpu: { type: "number" },
+								memMB: { type: "number" },
+								startTime: { type: "string" },
+								path: { type: "string" }
+							}
+						}
+					},
+					killed: { type: "integer" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => {
+				if (value.error !== void 0) return text("process error: " + value.error);
+				if (value.processes !== void 0) {
+					if (value.processes.length === 0) return text("no processes");
+					return text([
+						"id | name | cpu | memMB | startTime",
+						"--- | --- | --- | --- | ---",
+						...value.processes.map((p) => `${p.id} | ${p.name} | ${p.cpu ?? ""} | ${p.memMB ?? ""} | ${p.startTime ?? ""}`)
+					].join("\n"));
+				}
+				return text(`killed process ${value.killed ?? 0}`);
+			}
+		},
+		async execute(args) {
+			try {
+				if (args.action === "kill" && args.id !== void 0) {
+					await engine.killProcess(args.alias, args.id);
+					return { killed: args.id };
+				}
+				return { processes: await engine.listProcesses(args.alias) };
+			} catch (error) {
+				return { error: error instanceof Error ? error.message : String(error) };
+			}
+		}
+	});
+}
+/** The upload tool. */
+function winrmUploadTool(engine) {
+	return defineTool({
+		name: "winrm_upload",
+		description: "Upload a local file to a configured Windows host (SMB admin share preferred, base64 WinRM chunk fallback). The local path is on THIS machine (the dsh host). Triggers: upload file to Windows server, deploy artifact, copy config to Windows server.",
+		parameters: {
+			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 (base64 chunks), or auto (default, SMB first with WinRM fallback)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					transferredBytes: { type: "integer" },
+					channel: {
+						type: "string",
+						enum: ["smb", "winrm"]
+					},
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? `uploaded ${value.transferredBytes ?? 0} bytes via ${value.channel ?? "unknown"}` : `upload failed: ${value.error ?? "unknown error"}`)
+		},
+		async execute(args) {
+			try {
+				const outcome = await engine.upload(args.alias, args.localPath, args.remotePath, void 0, args.channel ?? "auto");
+				const usedChannel = outcome.channel === "smb" ? "smb" : "winrm";
+				return {
+					ok: true,
+					transferredBytes: outcome.bytes,
+					channel: usedChannel
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
+/** The download tool. */
+function winrmDownloadTool(engine) {
+	return defineTool({
+		name: "winrm_download",
+		description: "Download a remote FILE from a configured Windows host to a local path on this machine (SMB admin share preferred, base64 WinRM chunk fallback). Directory download is not supported — download files individually. Triggers: download file from Windows server, fetch remote log/artifact.",
+		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 (base64 chunks), or auto (default, SMB first with WinRM fallback)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					bytes: { type: "integer" },
+					channel: {
+						type: "string",
+						enum: ["smb", "winrm"]
+					},
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? `downloaded ${value.bytes ?? 0} bytes via ${value.channel ?? "unknown"}` : `download failed: ${value.error ?? "unknown error"}`)
+		},
+		async execute(args) {
+			try {
+				const outcome = await engine.download(args.alias, args.remotePath, args.localPath, void 0, args.channel ?? "auto");
+				const usedChannel = outcome.channel === "smb" ? "smb" : "winrm";
+				return {
+					ok: true,
+					bytes: outcome.bytes,
+					channel: usedChannel
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
+/** The cluster tool. */
+function winrmClusterTool(engine) {
+	return defineTool({
+		name: "winrm_cluster",
+		description: "Run one PowerShell command concurrently across many Windows hosts (all hosts, or filtered by aliases / environment / tags). Triggers: run on all Windows servers, batch operation, production servers, cluster command.",
+		parameters: {
+			command: {
+				type: "string",
+				required: true,
+				description: "The PowerShell command to run on every matched host."
+			},
+			aliases: {
+				type: "array",
+				items: { type: "string" },
+				description: "Explicit alias list; when absent every configured host matches."
+			},
+			environment: {
+				type: "string",
+				description: "Only hosts with this environment label."
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "Only hosts carrying ALL these tags."
+			},
+			timeoutMs: {
+				type: "integer",
+				description: "Per-host timeout in milliseconds."
+			},
+			maxWorkers: {
+				type: "integer",
+				description: "Concurrency cap (default 8)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { results: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							alias: {
+								type: "string",
+								required: true
+							},
+							ok: {
+								type: "boolean",
+								required: true
+							},
+							exitCode: { oneOf: [{ type: "integer" }, { type: "null" }] },
+							timedOut: { type: "boolean" },
+							stdout: { type: "string" },
+							stderr: { type: "string" },
+							durationMs: { type: "integer" },
+							error: { type: "string" }
+						}
+					}
+				} }
+			},
+			render: (_args, value) => text(renderCluster(value.results ?? []))
+		},
+		async execute(args) {
+			return { results: await engine.cluster(args) };
+		}
+	});
+}
+//#endregion
+//#region src/mount-once.ts
+/**
+* Host single-instance guard shared by the plugin family. The family bundle
+* (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+* the loader accepts a standalone install of the same package side by side;
+* without this guard the second instance would still re-register the same
+* webserver routes, tools, settings namespaces, and system-prompt sections
+* and fail the boot. mountOnce makes the second host apply a no-op for the
+* lifetime of the first instance (the browser half is already deduped by
+* package name in the client module host).
+*
+* The registry rides a global symbol so two module instances of the same
+* package (npm copy vs repository link) still share one verdict. cordis
+* `ctx.effect` runs its callback immediately and treats the callback's
+* return value as the fiber disposer, so the unmarker is returned, not run.
+*/
+const MOUNTED = Symbol.for("dsh-web-ui.mounted-plugins");
+function mountedSet() {
+	const registry = globalThis;
+	return registry[MOUNTED] ??= /* @__PURE__ */ new Set();
+}
+/**
+* Wrap a cordis plugin apply so the package runs at most once per process.
+* The first mount registers normally and unmarks when its fiber disposes;
+* any later mount of the same package name is a no-op.
+* @param packageName - npm package identity shared by every install source.
+* @param fn - the original plugin apply.
+* @returns an apply of the same shape.
+*/
+function mountOnce(packageName, fn) {
+	return ((...args) => {
+		const mounted = mountedSet();
+		if (mounted.has(packageName)) return;
+		mounted.add(packageName);
+		args[0]?.effect?.(() => () => {
+			mounted.delete(packageName);
+		});
+		return fn(...args);
+	});
+}
+//#endregion
+//#region src/index.ts
+/** Stable cordis plugin name. */
+const name = "winrm";
+/** Services required before the WinRM surfaces can mount. */
+const inject = [
+	"webServer",
+	"tools",
+	"systemPrompt"
+];
+const Config = z.object({
+	announceToAgent: z.boolean().default(true).volatile(),
+	enabled: z.boolean().default(true).volatile()
+});
+/** Schema default, re-read for hand-built test contexts. */
+const DEFAULT_ANNOUNCE = true;
+/** Schema default for the master switch. */
+const DEFAULT_ENABLED = true;
+/** Order of the announcement section within the tool-guidance band. */
+const SECTION_ORDER = 151;
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+const WINRM_GUIDANCE = "本机已安装 dsh-winrm 插件（DSH 远程 Windows 运维，WinRM/PowerShell Remoting）：侧边栏「Windows」入口；仿照 dsh-ssh 插件开发。能力：主机配置存 ~/.dsh/dsh-winrm.json（GUI 配置后 agent 方可使用）；winrm_list 列出主机、winrm_exec 执行 PowerShell 命令（UTF-8 信封，中文不乱码）、winrm_service 服务管理（start/stop/restart/启动类型）、winrm_process 进程管理（list/kill）、winrm_upload/winrm_download 文件传输（base64 分块，无 SMB 依赖）、winrm_cluster 集群并发执行；Web 控制台走 WebSocket。认证：通过原生 Node.js WinRM 客户端（winrm-client）的 NTLM/Negotiate 与 Basic 实现，兼容本地账户与域账户；传输支持 http(5985)/https(5986)。前提：目标机需启用 WinRM（scripts/enable-winrm.ps1），本机无需 Python —— WinRM 走纯 Node 依赖。HTTP 仅建议受信内网使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出可能含敏感信息；传输/执行消耗真实远程资源，先确认再操作。用户提到「Windows 服务器 / WinRM / PowerShell 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
+/**
+* Mount the WinRM engine, routes, tools, and announcement.
+* @param ctx - host plugin context carrying webServer/tools/systemPrompt.
+* @param config - resolved plugin config (volatile fields read via `.get()`).
+*/
+const apply = mountOnce("dsh-winrm", applyImpl);
+function applyImpl(ctx, config) {
+	const resolve = () => ({
+		announceToAgent: config?.announceToAgent?.get() ?? DEFAULT_ANNOUNCE,
+		enabled: config?.enabled?.get() ?? DEFAULT_ENABLED
+	});
+	const store = new HostStore();
+	const engine = new WinRmEngine(store);
+	const { routes, upgrade } = makeRoutes({
+		store,
+		engine
+	});
+	const tools = [
+		winrmListTool(engine),
+		winrmExecTool(engine),
+		winrmServiceTool(engine),
+		winrmProcessTool(engine),
+		winrmUploadTool(engine),
+		winrmDownloadTool(engine),
+		winrmClusterTool(engine)
+	];
+	let disposeSection;
+	let disposeRoutes;
+	let disposeTools;
+	const registerRoutes = () => {
+		const disposers = routes.map((route) => ctx.webServer.register(route));
+		const upgradeDisposer = ctx.webServer.registerUpgrade(upgrade);
+		return () => {
+			for (const dispose of disposers) dispose();
+			upgradeDisposer();
+		};
+	};
+	const registerTools = () => {
+		const disposers = tools.map((tool) => ctx.tools.register(tool));
+		return () => {
+			for (const dispose of disposers) dispose();
+		};
+	};
+	const sync = () => {
+		disposeSection?.();
+		disposeSection = void 0;
+		disposeRoutes?.();
+		disposeRoutes = void 0;
+		disposeTools?.();
+		disposeTools = void 0;
+		const value = resolve();
+		if (!value.enabled) return;
+		if (value.announceToAgent) disposeSection = ctx.systemPrompt.section({
+			name: "plugin:dsh-winrm",
+			order: SECTION_ORDER,
+			text: WINRM_GUIDANCE
+		});
+		disposeRoutes = registerRoutes();
+		disposeTools = registerTools();
+	};
+	ctx.on("loader/volatile-update", sync);
+	ctx.effect(() => () => {
+		disposeSection?.();
+		disposeRoutes?.();
+		disposeTools?.();
+		engine.dispose();
+	}, "dsh-winrm: teardown");
+	sync();
+}
+//#endregion
+export { Config, WINRM_GUIDANCE, apply, inject, name };