better-dsh 0.3.0 → 0.3.1-a

package/lib/remote/plugin.js

@@ -1,19 +1,498 @@
 import { t as Schema } from "../lib-C8_jXvwA.js";
-import { randomBytes } from "node:crypto";
-import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { Context } from "@deepseek-ai/cordis";
-import { homedir } from "node:os";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { constants, createReadStream, createWriteStream, mkdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { createConnection, createServer } from "node:net";
 
-//#region src/remote/oneshot.ts
-/** 单流硬收集帽（4M UTF-16 code units，ASCII≈4MB）：防失控输出吃内存；模型面截断由上层 tailWindow 负责。 */
-const HARD_CAP = 4e6;
-/** One-shot：子进程退出码即收尾（spec §五.1），stdout/stderr 分离保留。 */
-async function runOneShot(argv, opts = {}) {
+//#region src/remote/archive.ts
+const FILE_FRAME_BYTES = 64 * 1024;
+const FILE_MAX_ENTRIES = 1e4;
+const FILE_MAX_METADATA = 8 * 1024 * 1024;
+const order = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+function checkRelative(p) {
+	if (typeof p !== "string" || Buffer.byteLength(p) > 4096 || p.includes("\0") || p !== "" && (p.startsWith("/") || p.split("/").some((s) => !s || s === "." || s === ".."))) throw new Error("unsafe archive relative path");
+}
+function checkAbsolute(p) {
+	if (typeof p !== "string" || !p.startsWith("/") || p.includes("\0") || p.split("/").includes("..")) throw new Error("file endpoint requires an absolute path without traversal or NUL");
+}
+function checkSelection(selection) {
+	if (selection.length > FILE_MAX_ENTRIES || Buffer.byteLength(JSON.stringify(selection)) > FILE_MAX_METADATA) throw new Error("file selection metadata limit exceeded");
+	const seen = /* @__PURE__ */ new Set();
+	for (const p of selection) {
+		checkRelative(p);
+		if (seen.has(p)) throw new Error("duplicate selection path");
+		seen.add(p);
+	}
+}
+function checkLink(e) {
+	const link = e.link;
+	if (e.p === "" || typeof link !== "string" || !link || link.includes("\0") || link.startsWith("/") || Buffer.byteLength(link) > 4096) throw new Error("unsafe archive symlink");
+	const target = posix.normalize(posix.join(posix.dirname(e.p), link));
+	if (target === ".." || target.startsWith("../")) throw new Error("unsafe archive symlink escape");
+}
+/** Conservative effective resolution: links may traverse only members of this incoming tree.
+* Preserved destination extras cannot supply a symlink target or any of its ancestors.
+*/
+function checkTreeLinks(entries) {
+	const incoming = new Map(entries.map((e) => [e.p, e]));
+	for (const link of entries.filter((e) => e.t === "l")) {
+		const stack = posix.dirname(link.p) === "." ? [] : posix.dirname(link.p).split("/");
+		let pending = link.link.split("/"), hops = 0;
+		while (pending.length) {
+			const part = pending.shift();
+			if (!part || part === ".") continue;
+			if (part === "..") {
+				if (!stack.length) throw new Error("unsafe symlink chain escape");
+				stack.pop();
+				continue;
+			}
+			const entry = incoming.get([...stack, part].join("/"));
+			if (!entry) throw new Error("unsafe symlink target outside incoming tree (destination aliases are not followed)");
+			if (entry.t === "l") {
+				if (++hops > 40) throw new Error("unsafe symlink cycle or chain limit");
+				pending = [...entry.link.split("/"), ...pending];
+			} else {
+				if (pending.length && entry.t !== "d") throw new Error("unsafe symlink non-directory target ancestor");
+				stack.push(part);
+			}
+		}
+	}
+}
+function header(e) {
+	const b = Buffer.from(JSON.stringify(e)), n = Buffer.alloc(4);
+	n.writeUInt32BE(b.length);
+	return Buffer.concat([n, b]);
+}
+function manifestDigest(entries) {
+	const hash = createHash("sha256");
+	let bytes = 0;
+	for (const e of [...entries].sort((a, b) => order(a.p, b.p))) {
+		hash.update(header([
+			e.p,
+			e.t,
+			e.n,
+			e.t === "f" ? e.hash : e.t === "l" ? e.link : ""
+		]));
+		if (e.t === "f") bytes += e.n;
+	}
+	return {
+		sha256: hash.digest("hex"),
+		bytes,
+		entries: entries.length
+	};
+}
+/** Reject even existing parent symlinks; leaf may be an explicitly copied symlink. */
+async function ancestors(path$1, includeLeaf = false) {
+	checkAbsolute(path$1);
+	const parts = resolve(path$1).split("/").filter(Boolean);
+	for (let i = 1; i <= parts.length - (includeLeaf ? 0 : 1); i++) try {
+		const st = await lstat("/" + parts.slice(0, i).join("/"));
+		if (st.isSymbolicLink() || !st.isDirectory()) throw new Error("unsafe destination/source ancestor: symlink or non-directory");
+	} catch (e) {
+		if (e.code !== "ENOENT") throw e;
+	}
+}
+async function safeRead(path$1, signal) {
+	return (await open(path$1, constants.O_RDONLY | constants.O_NOFOLLOW)).createReadStream({
+		autoClose: true,
+		highWaterMark: FILE_FRAME_BYTES,
+		signal
+	});
+}
+async function entryAt(root, p, signal) {
+	signal.throwIfAborted();
+	const path$1 = p ? join(root, p) : root;
+	await ancestors(path$1);
+	const st = await lstat(path$1);
+	if (st.isDirectory()) return {
+		p,
+		t: "d",
+		n: 0
+	};
+	if (st.isSymbolicLink()) {
+		const e = {
+			p,
+			t: "l",
+			n: 0,
+			link: await readlink(path$1)
+		};
+		checkLink(e);
+		return e;
+	}
+	if (!st.isFile()) throw new Error("unsupported file type (only files, directories and safe relative symlinks)");
+	const hash = createHash("sha256");
+	for await (const chunk of await safeRead(path$1, signal)) hash.update(chunk);
+	return {
+		p,
+		t: "f",
+		n: st.size,
+		hash: hash.digest("hex")
+	};
+}
+async function tree(root, signal, selection) {
+	checkAbsolute(root);
+	const entries = [];
+	const visit = async (p) => {
+		const e = await entryAt(root, p, signal);
+		entries.push(e);
+		if (entries.length > FILE_MAX_ENTRIES) throw new Error("archive entry limit exceeded");
+		if (e.t === "d") for (const name$1 of (await readdir(p ? join(root, p) : root)).sort(order)) await visit(p ? `${p}/${name$1}` : name$1);
+	};
+	if (selection) {
+		checkSelection(selection);
+		for (const p of selection) entries.push(await entryAt(root, p, signal));
+	} else await visit("");
+	if (Buffer.byteLength(JSON.stringify(entries)) > FILE_MAX_METADATA) throw new Error("archive metadata limit exceeded");
+	return entries;
+}
+async function inspectArchive(path$1, signal) {
+	const file = await open(path$1, "r");
+	let offset = 0, metadata = 0;
+	const entries = [];
+	const seen = /* @__PURE__ */ new Map();
+	const exact = async (n) => {
+		const b = Buffer.alloc(n);
+		let at = 0;
+		while (at < n) {
+			signal.throwIfAborted();
+			const r = await file.read(b, at, n - at, offset);
+			if (!r.bytesRead) throw new Error("truncated binary archive");
+			at += r.bytesRead;
+			offset += r.bytesRead;
+		}
+		return b;
+	};
+	try {
+		while (true) {
+			const size = (await exact(4)).readUInt32BE();
+			if (!size || size > FILE_FRAME_BYTES) throw new Error("archive header limit exceeded");
+			metadata += size;
+			if (metadata > FILE_MAX_METADATA) throw new Error("archive metadata limit exceeded");
+			const e = JSON.parse((await exact(size)).toString("utf8"));
+			if (e.end === true) {
+				if ((await file.stat()).size !== offset) throw new Error("trailing archive bytes");
+				break;
+			}
+			checkRelative(e.p);
+			if (![
+				"f",
+				"d",
+				"l"
+			].includes(e.t) || !Number.isSafeInteger(e.n) || e.n < 0 || e.t !== "f" && e.n !== 0) throw new Error("unsafe archive type/size");
+			if (entries.length >= FILE_MAX_ENTRIES || seen.has(e.p)) throw new Error("archive entry limit or duplicate path");
+			if (e.p !== "" && seen.get(posix.dirname(e.p) === "." ? "" : posix.dirname(e.p))?.t !== "d") throw new Error("unsafe archive parent ordering/type");
+			if (!entries.length && e.p !== "") throw new Error("archive root missing");
+			if (e.t === "l") checkLink(e);
+			e.offset = offset;
+			if (e.t === "f") {
+				const hash = createHash("sha256");
+				let left = e.n;
+				while (left) {
+					const chunk = await exact(Math.min(FILE_FRAME_BYTES, left));
+					hash.update(chunk);
+					left -= chunk.length;
+				}
+				e.hash = hash.digest("hex");
+			}
+			entries.push(e);
+			seen.set(e.p, e);
+		}
+		if (!entries.length) throw new Error("archive root missing");
+		return entries;
+	} finally {
+		await file.close();
+	}
+}
+async function importArchive(destination, payload, mkdirParents, signal, resources) {
+	checkAbsolute(destination);
+	const entries = await inspectArchive(payload, signal);
+	checkTreeLinks(entries);
+	for (const e of entries) {
+		const path$1 = e.p ? join(destination, e.p) : destination;
+		await ancestors(path$1);
+		try {
+			const st = await lstat(path$1);
+			const type = st.isSymbolicLink() ? "l" : st.isDirectory() ? "d" : st.isFile() ? "f" : "?";
+			if (type !== e.t || type === "l") throw new Error("destination path/type conflict or existing symlink");
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+	}
+	await ancestors(destination);
+	if (mkdirParents) await mkdir(dirname(destination), { recursive: true });
+	for (const e of entries) {
+		signal.throwIfAborted();
+		const path$1 = e.p ? join(destination, e.p) : destination;
+		await ancestors(path$1);
+		if (e.t === "d") {
+			await mkdir(path$1, { recursive: false }).catch((error) => {
+				if (error.code !== "EEXIST") throw error;
+			});
+			continue;
+		}
+		if (e.t === "l") {
+			await symlink(e.link, path$1);
+			continue;
+		}
+		const temporary = join(dirname(path$1), `.remote-copy-${randomUUID()}`);
+		await resources.temporary?.(temporary, true);
+		try {
+			const output = createWriteStream(temporary, {
+				flags: "wx",
+				mode: 384
+			});
+			await pipeline(e.n ? createReadStream(payload, {
+				start: e.offset,
+				end: e.offset + e.n - 1
+			}) : Readable.from([]), output, { signal });
+			await ancestors(path$1);
+			signal.throwIfAborted();
+			await rename(temporary, path$1);
+		} finally {
+			await rm(temporary, { force: true });
+			await resources.temporary?.(temporary, false);
+		}
+	}
+}
+function localFileEndpoint(resources = {}) {
+	return {
+		async exportTree(path$1, signal) {
+			const entries = await tree(path$1, signal);
+			return Readable.from((async function* () {
+				for (const e of entries) {
+					signal.throwIfAborted();
+					yield header({
+						p: e.p,
+						t: e.t,
+						n: e.n,
+						...e.link === void 0 ? {} : { link: e.link }
+					});
+					if (e.t === "f" && e.n) for await (const chunk of await safeRead(e.p ? join(path$1, e.p) : path$1, signal)) yield chunk;
+				}
+				yield header({ end: true });
+			})());
+		},
+		async importTree(path$1, source, { mkdir: parents, signal }) {
+			checkAbsolute(path$1);
+			const scratch = resources.receiveRoot ?? await mkdtemp(join(tmpdir(), "remote-file-receive-"));
+			try {
+				const payload = join(scratch, "payload");
+				await pipeline(source, createWriteStream(payload, {
+					flags: "wx",
+					mode: 384
+				}), { signal });
+				await importArchive(path$1, payload, parents, signal, resources);
+			} finally {
+				source.destroy?.();
+				await rm(scratch, {
+					recursive: true,
+					force: true
+				});
+			}
+		},
+		async digest(path$1, signal, selection) {
+			return manifestDigest(await tree(path$1, signal, selection));
+		}
+	};
+}
+
+//#endregion
+//#region src/remote/copy.ts
+var CopyError = class extends Error {
+	constructor(receipt) {
+		super(`copy failed: ${JSON.stringify(receipt)}`);
+		this.receipt = receipt;
+	}
+};
+/** Tree lane (Hub/local binary endpoints) with staged archive and digest
+* verification. CLI-option fields are rejected: this lane has no native CLI. */
+async function copyTree(request, source, destination, signal, scratchRoot = join(process.cwd(), ".scratch")) {
+	signal.throwIfAborted();
+	if (request.argv !== void 0 || request.pullArgv !== void 0 || request.pushArgv !== void 0) throw new Error("copy: argv/pullArgv/pushArgv are native CLI options; the Hub/local staged lane does not accept CLI options");
+	await mkdir(scratchRoot, { recursive: true });
+	signal.throwIfAborted();
+	const scratch = await mkdtemp(join(scratchRoot, "remote-copy-")), payload = join(scratch, "payload.bin");
+	const receipt = {
+		action: "copy",
+		src: request.src,
+		dst: request.dst,
+		verified: false,
+		bytes: 0,
+		entries: 0,
+		scope: "transferred entries"
+	};
+	try {
+		await pipeline(await source.endpoint.exportTree(source.path, signal), createWriteStream(payload, {
+			flags: "wx",
+			mode: 384
+		}), { signal });
+		const manifest = await inspectArchive(payload, signal), staged = manifestDigest(manifest);
+		receipt.bytes = staged.bytes;
+		receipt.entries = staged.entries;
+		const selection = manifest.map((e) => e.p);
+		if (request.verify !== false) {
+			const original = await source.endpoint.digest(source.path, signal, selection);
+			receipt.sourceDigest = original.sha256;
+			if (original.sha256 !== staged.sha256) throw new Error("source changed during export; staged digest mismatch");
+		}
+		signal.throwIfAborted();
+		await destination.endpoint.importTree(destination.path, createReadStream(payload), {
+			mkdir: request.mkdir ?? true,
+			signal
+		});
+		if (request.verify !== false) {
+			const dest = await destination.endpoint.digest(destination.path, signal, selection);
+			receipt.destinationDigest = dest.sha256;
+			if (dest.sha256 !== receipt.sourceDigest) throw new Error("destination digest mismatch");
+			receipt.verified = true;
+		}
+		signal.throwIfAborted();
+		await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+		return receipt;
+	} catch (error) {
+		throw new CopyError({
+			...receipt,
+			verified: false,
+			scratch,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+
+//#endregion
+//#region src/remote/output-ring.ts
+const continuation = (byte) => (byte & 192) === 128;
+function completeUtf8End(bytes) {
+	if (!bytes.length) return 0;
+	let start = bytes.length - 1;
+	while (start > 0 && continuation(bytes[start]) && bytes.length - start < 4) start--;
+	const lead = bytes[start];
+	const width = lead >= 240 && lead <= 244 ? 4 : lead >= 224 && lead <= 239 ? 3 : lead >= 194 && lead <= 223 ? 2 : 1;
+	return bytes.length - start < width ? start : bytes.length;
+}
+/** Byte-addressed decoded output: mid-codepoint cursors skip forward and explicitly report loss. */
+function readUtf8Tail(bytes, totalBytes, fromByte) {
+	if (!Number.isSafeInteger(fromByte) || fromByte < 0) throw new Error("Output cursor must be a non-negative safe byte offset");
+	const start = totalBytes - bytes.length;
+	let offset = Math.max(0, Math.min(bytes.length, fromByte - start));
+	let lossy = fromByte < start;
+	while (offset < bytes.length && continuation(bytes[offset])) {
+		offset++;
+		lossy = true;
+	}
+	const end = completeUtf8End(bytes);
+	return {
+		text: bytes.subarray(Math.min(offset, end), end).toString("utf8"),
+		nextOffset: start + end,
+		lossy
+	};
+}
+/** Native/PTY retention is UTF16 units; cursor offsets remain real UTF8 bytes. Input is decoded text. */
+var Utf16TailRing = class {
+	text = "";
+	total = 0;
+	totalBytes = 0;
+	constructor(capacity = 4e6) {
+		this.capacity = capacity;
+	}
+	push(text) {
+		this.total += text.length;
+		this.totalBytes += Buffer.byteLength(text);
+		this.text = (this.text + text).slice(-this.capacity);
+		if (this.text.charCodeAt(0) >= 56320 && this.text.charCodeAt(0) <= 57343) this.text = this.text.slice(1);
+	}
+	stats(returned = this.text.length) {
+		return {
+			unit: "utf16",
+			total: this.total,
+			retained: this.text.length,
+			dropped: this.total - this.text.length,
+			returned,
+			retentionLimit: this.capacity
+		};
+	}
+	read(fromByte) {
+		return readUtf8Tail(Buffer.from(this.text), this.totalBytes, fromByte);
+	}
+};
+/** Raw byte retention for Hub oneshot. Tail/read starts skip partial UTF8 prefixes, never invent replacement characters. */
+var ByteTailRing = class {
+	total = 0;
+	chunks = [];
+	retained = 0;
+	constructor(capacity = 4 * 1024 * 1024) {
+		this.capacity = capacity;
+	}
+	push(chunk) {
+		if (chunk.length === 0) return;
+		this.total += chunk.length;
+		this.chunks.push(chunk);
+		this.retained += chunk.length;
+		let drop = this.retained - this.capacity;
+		while (drop > 0) {
+			const head = this.chunks[0];
+			const count = Math.min(drop, head.length);
+			if (count === head.length) this.chunks.shift();
+			else this.chunks[0] = head.subarray(count);
+			this.retained -= count;
+			drop -= count;
+		}
+	}
+	tail(maxBytes = this.retained) {
+		let skip = Math.max(0, this.retained - maxBytes);
+		const out = [];
+		for (const chunk of this.chunks) {
+			if (skip >= chunk.length) {
+				skip -= chunk.length;
+				continue;
+			}
+			out.push(chunk.subarray(skip));
+			skip = 0;
+		}
+		const bytes = Buffer.concat(out);
+		let offset = 0;
+		while (offset < bytes.length && continuation(bytes[offset])) offset++;
+		return bytes.subarray(offset, completeUtf8End(bytes));
+	}
+	stats(returned = this.tail().length) {
+		return {
+			unit: "bytes",
+			total: this.total,
+			retained: this.retained,
+			dropped: this.total - this.retained,
+			returned,
+			retentionLimit: this.capacity
+		};
+	}
+	read(fromByte) {
+		return readUtf8Tail(Buffer.concat(this.chunks), this.total, fromByte);
+	}
+};
+
+//#endregion
+//#region src/remote/process.ts
+const TERM_GRACE_MS = 2e3;
+const KILL_SETTLE_MS = 100;
+const PROCESS_CLEANUP_BOUND_MS = TERM_GRACE_MS + KILL_SETTLE_MS;
+/** Real detached process. Completion includes group cleanup, even after its leader closes. */
+function startBinaryProcess(argv, options = {}) {
 	const started = Date.now();
 	const child = spawn(argv[0], argv.slice(1), {
+		cwd: options.cwd,
+		env: options.env === void 0 ? process.env : {
+			...process.env,
+			...options.env
+		},
 		stdio: [
 			"pipe",
 			"pipe",
@@ -21,57 +500,1075 @@ async function runOneShot(argv, opts = {}) {
 		],
 		detached: true
 	});
-	let stdout = "";
-	let stderr = "";
-	let timedOut = false;
-	child.stdout.setEncoding("utf8").on("data", (d) => {
-		if (stdout.length < HARD_CAP) stdout = (stdout + d).slice(0, HARD_CAP);
+	let diagnostic;
+	let timedOut = false, finished = false, cancelled = false;
+	let cleanup;
+	let timer;
+	const signal = (sig) => {
+		if (child.pid === void 0) return false;
+		try {
+			process.kill(-child.pid, sig);
+			return true;
+		} catch (error) {
+			if (error.code !== "ESRCH") diagnostic = `remote: process cleanup failed: ${String(error)}`;
+			return false;
+		}
+	};
+	let closed;
+	const close = new Promise((resolve$1) => {
+		closed = resolve$1;
 	});
-	child.stderr.setEncoding("utf8").on("data", (d) => {
-		if (stderr.length < HARD_CAP) stderr = (stderr + d).slice(0, HARD_CAP);
+	const reap = () => cleanup ??= new Promise((resolve$1) => {
+		if (!signal("SIGTERM")) {
+			resolve$1();
+			return;
+		}
+		let settled = false;
+		const finish = () => {
+			if (!settled) {
+				settled = true;
+				clearTimeout(grace);
+				resolve$1();
+			}
+		};
+		const grace = setTimeout(() => {
+			signal("SIGKILL");
+			setTimeout(finish, KILL_SETTLE_MS);
+		}, TERM_GRACE_MS);
+		close.then(() => {
+			if (!signal(0)) finish();
+		});
 	});
+	const cancel = () => {
+		if (!finished) {
+			cancelled = true;
+			reap();
+		}
+	};
 	child.stdin.on("error", () => {});
-	if (opts.stdin !== void 0) child.stdin.write(opts.stdin);
-	child.stdin.end();
-	let termTimer;
-	let killTimer;
-	const clearTimers = () => {
-		if (termTimer !== void 0) clearTimeout(termTimer);
-		if (killTimer !== void 0) clearTimeout(killTimer);
+	child.once("error", (error) => {
+		diagnostic = `exec: spawn failed — ${error.message}${options.cwd === void 0 ? "" : ` (cwd: ${options.cwd})`}`;
+	});
+	const done = new Promise((resolve$1) => {
+		child.once("close", async (exit) => {
+			closed();
+			if (timer) clearTimeout(timer);
+			await reap();
+			finished = true;
+			resolve$1({
+				exit: diagnostic ? null : exit,
+				timedOut,
+				cancelled,
+				durationMs: Date.now() - started
+			});
+		});
+	});
+	if (options.timeoutSec !== void 0) timer = setTimeout(() => {
+		timedOut = true;
+		cancel();
+	}, options.timeoutSec * 1e3);
+	return {
+		cancel,
+		done,
+		stdout: child.stdout,
+		stderr: child.stderr,
+		stdin: child.stdin,
+		diagnostic: () => diagnostic
 	};
-	if (opts.timeoutSec !== void 0) {
-		const killGroup = (sig) => {
-			if (child.pid === void 0) {
-				child.kill(sig);
-				return;
-			}
-			try {
-				process.kill(-child.pid, sig);
-			} catch {}
+}
+/** Text adapter over the same owned process-group lifecycle as binary pipelines. */
+function startOneShot(argv, options = {}) {
+	const child = startBinaryProcess(argv, options);
+	const byteMode = options.unit === "bytes";
+	const stdout = byteMode ? new ByteTailRing() : new Utf16TailRing();
+	const stderr = byteMode ? new ByteTailRing() : new Utf16TailRing();
+	for (const [stream, ring] of [[child.stdout, stdout], [child.stderr, stderr]]) {
+		if (!byteMode) stream.setEncoding("utf8");
+		stream.on("data", (chunk) => {
+			if (ring instanceof ByteTailRing) ring.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+			else ring.push(String(chunk));
+			options.onOutput?.();
+		});
+	}
+	child.stdin.end(options.stdin);
+	return {
+		cancel: child.cancel,
+		done: child.done,
+		read(channel, fromByte) {
+			const ring = channel === "stdout" ? stdout : stderr;
+			const read = ring.read(fromByte), diagnostic = child.diagnostic();
+			return {
+				...read,
+				stats: ring.stats(byteMode ? Buffer.byteLength(read.text) : read.text.length),
+				...channel === "stderr" && diagnostic ? { diagnostic } : {}
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/remote/native-copy.ts
+const OUTPUT_LIMIT$1 = 512 * 1024;
+var ArgvError = class extends Error {
+	constructor(field, reason) {
+		super(`remote: ${field} must be an array of non-empty string tokens without NUL (${reason})`);
+	}
+};
+/** Ordered native option tokens; one element = one argv token, never shell-parsed. */
+function checkArgv(field, value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw new ArgvError(field, "got a non-array");
+	for (const token of value) {
+		if (typeof token !== "string" || token.length === 0) throw new ArgvError(field, "empty or non-string element");
+		if (token.includes("\0")) throw new ArgvError(field, "NUL byte in element");
+		if (token === "--") throw new ArgvError(field, "a bare -- would terminate option parsing and let later tokens act as extra source operands; src/dst cannot be overridden via argv");
+	}
+	return [...value];
+}
+/** scp -R re-authenticates to the destination FROM the source host, breaking the identities-stay-on-origin boundary. */
+function rejectRemoteToRemoteScp(argv) {
+	const boundary = "remote: scp -R would authenticate to the destination from the source host; identities must stay on the origin (scp -3 through-origin is the supported route)";
+	for (const token of argv) {
+		if (token === "-R" || token === "--remote-to-remote" || token === "--r") throw new Error(boundary);
+		if (token.startsWith("-") && !token.startsWith("--") && token.slice(1).includes("R")) throw new Error(boundary);
+	}
+}
+/** Run one native CLI with group-owned lifecycle; output bounded, exit verbatim.
+* `env` overlays process env (RSYNC_RSH wiring); values are tool-built argv, never model text. */
+async function runNative(argv, signal, env = {}) {
+	signal.throwIfAborted();
+	const child = startBinaryProcess(argv, { env: {
+		...process.env,
+		...env
+	} });
+	const cancel = () => child.cancel();
+	signal.addEventListener("abort", cancel, { once: true });
+	let stdout = "", stderr = "", truncated = false;
+	child.stdout.setEncoding("utf8");
+	child.stderr.setEncoding("utf8");
+	child.stdout.on("data", (text) => {
+		const value = stdout + text;
+		if (value.length > OUTPUT_LIMIT$1) truncated = true;
+		stdout = value.slice(-OUTPUT_LIMIT$1);
+	});
+	child.stderr.on("data", (text) => {
+		const value = stderr + text;
+		if (value.length > OUTPUT_LIMIT$1) truncated = true;
+		stderr = value.slice(-OUTPUT_LIMIT$1);
+	});
+	try {
+		const result = await child.done;
+		const diagnostic = child.diagnostic();
+		return {
+			exit: result.exit,
+			stdout,
+			stderr: diagnostic !== void 0 ? (stderr + "\n" + diagnostic).slice(-OUTPUT_LIMIT$1) : stderr,
+			outputTruncated: truncated || diagnostic !== void 0
 		};
-		termTimer = setTimeout(() => {
-			timedOut = true;
-			killGroup("SIGTERM");
-			killTimer = setTimeout(() => killGroup("SIGKILL"), 2e3);
-		}, opts.timeoutSec * 1e3);
-	}
-	const exit = await new Promise((resolve$1) => {
-		child.once("close", (code) => resolve$1(code));
-		child.once("error", (err) => {
-			stderr += `\n[remote: spawn failed: ${err.message}]`;
-			resolve$1(null);
+	} finally {
+		signal.removeEventListener("abort", cancel);
+	}
+}
+/** scp spec keeps identity in argv/config; caller -F/-i/-P override by scp's own precedence. */
+function scpSpec(connection, path$1) {
+	const host = connection.host.includes(":") ? `[${connection.host}]` : connection.host;
+	return `${connection.user !== void 0 ? `${connection.user}@${host}` : host}:${path$1}`;
+}
+/** Connection identity as scp options (port, key), placed BEFORE caller argv so
+* an explicit caller -F/-i/-P/-J overrides the registered identity by scp's own
+* precedence (last option wins). */
+function identityArgv(connection) {
+	const options = ["-o", "BatchMode=yes"];
+	if (connection.port !== void 0) options.push("-P", String(connection.port));
+	if (connection.key !== void 0) options.push("-i", connection.key);
+	if (connection.proxyJump !== void 0) options.push("-J", connection.proxyJump);
+	return options;
+}
+function sshEndpoint(plan) {
+	if (plan.kind !== "ssh") throw new Error("remote: native copy endpoint is not an SSH target");
+	return { connection: plan.connection ?? { host: plan.host } };
+}
+/** Container name for docker/incus endpoints (narrows without casts). */
+function containerOf(plan) {
+	if (plan.kind !== "docker" && plan.kind !== "incus") throw new Error("remote: native copy endpoint is not a container target");
+	return plan.container;
+}
+/**
+* One native copy.
+* - local↔SSH: scp; SSH↔SSH: scp -3 through origin (both identities here; when
+*   they differ a temp origin-only config maps two synthetic aliases)
+* - local↔docker: docker cp; local↔incus: incus file push/pull
+* - every other cross-endpoint pair: two native commands with origin staging,
+*   each segment with its own options (pullArgv/pushArgv)
+*/
+async function nativeCopy(request, endpoints, signal, options = {}) {
+	signal.throwIfAborted();
+	const oneShot = checkArgv("argv", request.argv);
+	const pull = checkArgv("pullArgv", request.pullArgv);
+	const push = checkArgv("pushArgv", request.pushArgv);
+	if (oneShot.length > 0 && (pull.length > 0 || push.length > 0)) throw new Error("remote: argv cannot be combined with pullArgv/pushArgv (argv is for single-command routes; pullArgv/pushArgv for two-segment routes)");
+	if (request.pullArgv !== void 0 && request.pushArgv === void 0) throw new Error("remote: pullArgv requires pushArgv (a two-segment copy has both halves)");
+	if (request.pushArgv !== void 0 && request.pullArgv === void 0) throw new Error("remote: pushArgv requires pullArgv (a two-segment copy has both halves)");
+	const wrap = options.wrapArgv ?? ((argv) => argv);
+	const s = endpoints.src.plan.kind, t = endpoints.dst.plan.kind;
+	const receipt = {
+		action: "copy",
+		src: request.src,
+		dst: request.dst,
+		route: "",
+		argv: [],
+		exits: [],
+		stdout: [],
+		stderr: [],
+		outputTruncated: false,
+		verified: false,
+		cleanup: "none-required"
+	};
+	const finish = (route, argvs, results) => {
+		receipt.route = route;
+		receipt.argv = argvs;
+		receipt.exits = results.map((result) => result.exit);
+		receipt.stdout = results.map((result) => result.stdout);
+		receipt.stderr = results.map((result) => result.stderr);
+		receipt.outputTruncated = results.some((result) => result.outputTruncated);
+		return receipt;
+	};
+	if (s === "local" && t === "ssh") {
+		rejectRemoteToRemoteScp(oneShot);
+		const connection = sshEndpoint(endpoints.dst.plan).connection;
+		const argv = [
+			"scp",
+			...identityArgv(connection),
+			...oneShot,
+			endpoints.src.path,
+			scpSpec(connection, endpoints.dst.path)
+		];
+		return finish("scp", [argv], [await runNative(wrap(argv), signal)]);
+	}
+	if (s === "ssh" && t === "local") {
+		rejectRemoteToRemoteScp(oneShot);
+		const connection = sshEndpoint(endpoints.src.plan).connection;
+		const argv = [
+			"scp",
+			...identityArgv(connection),
+			...oneShot,
+			scpSpec(connection, endpoints.src.path),
+			endpoints.dst.path
+		];
+		return finish("scp", [argv], [await runNative(wrap(argv), signal)]);
+	}
+	if (s === "ssh" && t === "ssh") {
+		rejectRemoteToRemoteScp(oneShot);
+		const source = sshEndpoint(endpoints.src.plan).connection, destination = sshEndpoint(endpoints.dst.plan).connection;
+		const sameIdentity = JSON.stringify(source) === JSON.stringify(destination);
+		let config;
+		let unknown = false;
+		try {
+			let srcSpec, dstSpec;
+			let extra = [];
+			if (sameIdentity) {
+				srcSpec = scpSpec(source, endpoints.src.path);
+				dstSpec = scpSpec(destination, endpoints.dst.path);
+				extra = identityArgv(source);
+			} else {
+				config = await tempSshConfig(source, destination);
+				extra = ["-F", config.path];
+				srcSpec = `superd-scp3-source:${endpoints.src.path}`;
+				dstSpec = `superd-scp3-destination:${endpoints.dst.path}`;
+			}
+			const argv = [
+				"scp",
+				"-3",
+				...extra,
+				...oneShot,
+				srcSpec,
+				dstSpec
+			];
+			return finish("scp -3 (data through origin)", [argv], [await runNative(wrap(argv), signal)]);
+		} catch (error) {
+			if (signal.aborted) unknown = true;
+			throw error;
+		} finally {
+			if (config !== void 0) receipt.cleanup = !await rm(config.dir, {
+				recursive: true,
+				force: true
+			}).then(() => true, () => false) || unknown ? "unknown" : "released";
+		}
+	}
+	if (s === "local" && t === "docker") {
+		const argv = [
+			"docker",
+			"cp",
+			...oneShot,
+			endpoints.src.path,
+			`${containerOf(endpoints.dst.plan)}:${endpoints.dst.path}`
+		];
+		return finish("docker cp", [argv], [await runNative(wrap(argv), signal)]);
+	}
+	if (s === "docker" && t === "local") {
+		const argv = [
+			"docker",
+			"cp",
+			...oneShot,
+			`${containerOf(endpoints.src.plan)}:${endpoints.src.path}`,
+			endpoints.dst.path
+		];
+		return finish("docker cp", [argv], [await runNative(wrap(argv), signal)]);
+	}
+	if (s === "local" && t === "incus") {
+		const argv = [
+			"incus",
+			"file",
+			"push",
+			...oneShot,
+			endpoints.src.path,
+			`${containerOf(endpoints.dst.plan)}${endpoints.dst.path}`
+		];
+		return finish("incus file push", [argv], [await runNative(wrap(argv), signal)]);
+	}
+	if (s === "incus" && t === "local") {
+		const argv = [
+			"incus",
+			"file",
+			"pull",
+			...oneShot,
+			`${containerOf(endpoints.src.plan)}${endpoints.src.path}`,
+			endpoints.dst.path
+		];
+		return finish("incus file pull", [argv], [await runNative(wrap(argv), signal)]);
+	}
+	if (s === "local" || t === "local") throw new Error("remote: this endpoint pair is a single native command route; pullArgv/pushArgv apply to cross-endpoint pairs only");
+	const pullOptions = request.pullArgv !== void 0 ? pull : oneShot;
+	const pushOptions = request.pushArgv !== void 0 ? push : oneShot;
+	const scratch = await mkdtemp(join(options.scratchRoot ?? join(process.cwd(), ".scratch"), "remote-native-copy-"));
+	const staged = join(scratch, "staged");
+	try {
+		rejectRemoteToRemoteScp(pullOptions);
+		rejectRemoteToRemoteScp(pushOptions);
+		const pullArgv = segmentArgv(endpoints.src.plan, endpoints.src.path, staged, pullOptions, "pull");
+		const pushArgv = segmentArgv(endpoints.dst.plan, endpoints.dst.path, staged, pushOptions, "push");
+		const first = await runNative(wrap(pullArgv), signal);
+		if (first.exit !== 0) return finish("two native commands with origin staging (push not started: pull failed)", [pullArgv], [first]);
+		const second = await runNative(wrap(pushArgv), signal);
+		return finish("two native commands with origin staging", [pullArgv, pushArgv], [first, second]);
+	} finally {
+		receipt.cleanup = await rm(scratch, {
+			recursive: true,
+			force: true
+		}).then(() => true, () => false) && !signal.aborted ? "released" : "unknown";
+	}
+}
+/** One segment of a two-segment route: pull remote→staging, or push staging→remote. */
+function segmentArgv(plan, remote, staged, opts, leg) {
+	if (plan.kind === "local") throw new Error("remote: two-segment staging connects two CLI peers, not a local path");
+	if (plan.kind === "ssh") {
+		const connection = sshEndpoint(plan).connection;
+		const spec$1 = scpSpec(connection, remote);
+		return leg === "pull" ? [
+			"scp",
+			...opts,
+			...identityArgv(connection),
+			spec$1,
+			staged
+		] : [
+			"scp",
+			...opts,
+			...identityArgv(connection),
+			staged,
+			spec$1
+		];
+	}
+	if (plan.kind === "docker") {
+		const spec$1 = `${plan.container}:${remote}`;
+		return leg === "pull" ? [
+			"docker",
+			"cp",
+			...opts,
+			spec$1,
+			staged
+		] : [
+			"docker",
+			"cp",
+			...opts,
+			staged,
+			spec$1
+		];
+	}
+	const spec = `${plan.container}${remote}`;
+	return leg === "pull" ? [
+		"incus",
+		"file",
+		"pull",
+		...opts,
+		spec,
+		staged
+	] : [
+		"incus",
+		"file",
+		"push",
+		...opts,
+		staged,
+		spec
+	];
+}
+/** Distinguishing identities for scp -3: an origin-only temp config maps two
+* synthetic aliases; keys are referenced in place, never copied to any remote. */
+async function tempSshConfig(source, destination) {
+	for (const c of [source, destination]) for (const [field, value] of [
+		["host", c.host],
+		["user", c.user],
+		["key", c.key],
+		["proxyJump", c.proxyJump]
+	]) if (value !== void 0 && /[\r\n]/.test(value)) throw new Error(`remote: scp -3 temp config rejects newline in SSH ${field} (no config injection)`);
+	const dir = await mkdtemp(join(tmpdir(), "superd-scp3-"));
+	const path$1 = join(dir, "config");
+	const block = (name$1, c) => {
+		const lines = [`Host ${name$1}`, `  HostName ${c.host.replace(/^.*@/, "")}`];
+		if (c.user !== void 0) lines.push(`  User ${c.user}`);
+		if (c.port !== void 0) lines.push(`  Port ${String(c.port)}`);
+		if (c.key !== void 0) lines.push(`  IdentityFile ${c.key}`);
+		if (c.proxyJump !== void 0) lines.push(`  ProxyJump ${c.proxyJump}`);
+		return lines.join("\n");
+	};
+	await writeFile(path$1, `${block("superd-scp3-source", source)}\n${block("superd-scp3-destination", destination)}\n`, { mode: 384 });
+	await chmod(path$1, 384);
+	return {
+		path: path$1,
+		dir
+	};
+}
+
+//#endregion
+//#region src/remote/ssh-rsync-native-relay.ts
+/** ssh argv for the relay: batch, no agent, no multiplexing. `command` is the
+* remote command; forwarding options go before `--`, the host after it. */
+function relaySsh(connection, extra, command) {
+	const args = [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-T",
+		"-a",
+		"-o",
+		"ForwardAgent=no",
+		"-o",
+		"ControlMaster=no",
+		"-o",
+		"ControlPath=none",
+		"-o",
+		"ConnectTimeout=10",
+		"-o",
+		"ServerAliveInterval=5",
+		"-o",
+		"ServerAliveCountMax=2"
+	];
+	if (connection.user !== void 0) args.push("-l", connection.user);
+	if (connection.port !== void 0) args.push("-p", String(connection.port));
+	if (connection.key !== void 0) args.push("-i", connection.key);
+	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
+	args.push(...extra, "--", connection.host);
+	if (command !== void 0) args.push(command);
+	return args;
+}
+async function freePorts(count) {
+	const servers = [];
+	try {
+		for (let i = 0; i < count; i++) {
+			const server = createServer();
+			const { promise, resolve: resolve$1, reject } = Promise.withResolvers();
+			server.once("error", reject);
+			server.listen(0, "127.0.0.1", resolve$1);
+			await promise;
+			servers.push(server);
+		}
+		const ports = servers.map((server) => server.address().port);
+		await Promise.all(servers.map((server) => new Promise((resolve$1) => server.close(() => resolve$1()))));
+		return ports;
+	} finally {
+		await Promise.all(servers.map((server) => new Promise((resolve$1) => server.close(() => resolve$1()))));
+	}
+}
+async function originPortOpen(port, timeoutMs) {
+	const until = Date.now() + timeoutMs;
+	for (;;) {
+		const { promise, resolve: resolve$1 } = Promise.withResolvers();
+		const socket = createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve$1(true);
+		});
+		socket.once("error", () => {
+			socket.destroy();
+			resolve$1(false);
+		});
+		if (await promise) return true;
+		if (Date.now() >= until) return false;
+		await new Promise((resolve$2) => setTimeout(resolve$2, 50));
+	}
+}
+/**
+* Dual-SSH rsync. Forwarding route first; on forwarding denial the stdio
+* route; if both are unavailable the combined facts are reported — never a
+* full-copy fallback.
+*/
+async function relayRsync(argv, source, destination, signal, options = {}) {
+	if (options.forceStdioRoute !== true) try {
+		return await forwardRoute(argv, source, destination, signal, options);
+	} catch (error) {
+		if (signal.aborted) throw signal.reason;
+		if (!forwardingDenied(error)) throw error;
+		try {
+			return await stdioRoute(argv, source, destination, signal, options);
+		} catch (stdioError) {
+			if (signal.aborted) throw signal.reason;
+			throw new Error(`dual-SSH rsync unavailable: forwarding route denied (${error instanceof Error ? error.message : String(error)}); stdio route failed (${stdioError instanceof Error ? stdioError.message : String(stdioError)}); no full-copy fallback is performed`, { cause: stdioError });
+		}
+	}
+	return stdioRoute(argv, source, destination, signal, options);
+}
+/** Forwarding was actually refused by an endpoint (admin policy), not any other failure. */
+function forwardingDenied(error) {
+	const text = error instanceof Error ? `${error.message}\n${String(error.cause ?? "")}` : String(error);
+	return /administratively prohibited|forwarding failed|could not request (local|remote) forwarding|AllowTcpForwarding/i.test(text);
+}
+const OUTPUT_LIMIT = 512 * 1024;
+/** Bounded stdout/stderr capture for a child stream. */
+function capture(stream, sink) {
+	const onText = (text) => {
+		const value = sink.text + text;
+		if (value.length > OUTPUT_LIMIT) sink.truncated = true;
+		sink.text = value.slice(-OUTPUT_LIMIT);
+	};
+	stream?.setEncoding("utf8");
+	stream?.on("data", onText);
+	return onText;
+}
+/** A held SSH child (forward/daemon carrier) with group shutdown and stderr. */
+var Held = class {
+	child;
+	done;
+	stderrSink = {
+		text: "",
+		truncated: false
+	};
+	stopped = false;
+	constructor(argv, signal) {
+		this.signal = signal;
+		signal.throwIfAborted();
+		this.child = spawn(argv[0], argv.slice(1), {
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: true
+		});
+		capture(this.child.stderr, this.stderrSink);
+		this.done = new Promise((resolve$1) => {
+			this.child.once("close", () => resolve$1());
 		});
+	}
+	async stop() {
+		if (this.stopped) {
+			await this.done;
+			return;
+		}
+		this.stopped = true;
+		if (this.child.pid !== void 0) try {
+			process.kill(-this.child.pid, "SIGTERM");
+		} catch {}
+		await Promise.race([this.done, new Promise((resolve$1) => setTimeout(resolve$1, 3e3))]);
+		if (this.child.exitCode === null && this.child.signalCode === null && this.child.pid !== void 0) try {
+			process.kill(-this.child.pid, "SIGKILL");
+		} catch {}
+		await this.done;
+	}
+};
+/**
+* Route A. Three SSH sessions, all origin-held:
+*  1. destination: -L + daemon script (daemon binds destination loopback only)
+*  2. source hold: -N -R maps origin daemon port onto source loopback
+*  3. source run: executes the native rsync client against its own loopback
+* rsync protocol bytes traverse source → origin → destination; nothing is
+* staged on the origin.
+*/
+async function forwardRoute(argv, source, destination, signal, options) {
+	signal.throwIfAborted();
+	const wrap = options.wrapArgv ?? ((value) => value);
+	const ports = options.ports?.daemon !== void 0 ? [options.ports.daemon, ...await freePorts(2)] : await freePorts(3);
+	const daemonPort = ports[0], originPort = ports[1], sourcePort = ports[2];
+	const destinationArgv = relaySsh(destination.connection, [
+		"-o",
+		"ExitOnForwardFailure=yes",
+		"-L",
+		`127.0.0.1:${originPort}:127.0.0.1:${daemonPort}`
+	], daemonCommand(destination.path, daemonPort));
+	const sourceHoldArgv = relaySsh(source.connection, [
+		"-o",
+		"ExitOnForwardFailure=yes",
+		"-N",
+		"-R",
+		`127.0.0.1:${sourcePort}:127.0.0.1:${originPort}`
+	]);
+	const destinationChild = new Held(wrap(destinationArgv), signal);
+	const sourceHold = new Held(wrap(sourceHoldArgv), signal);
+	const remoteTempOf = (held) => /^SUPERD-RSYNC-TMP (\S+)$/m.exec(held.stderrSink.text)?.[1];
+	const settle = async () => {
+		await Promise.all([destinationChild.stop(), sourceHold.stop()]);
+		const temp = remoteTempOf(destinationChild);
+		if (temp === void 0) return "unknown";
+		return await removeRemoteTemp(destination.connection, temp, wrap) ? "released" : "unknown";
+	};
+	try {
+		signal.throwIfAborted();
+		if (!await originPortOpen(originPort, 15e3)) throw new Error(`dual-SSH rsync destination daemon never became reachable${relayDetail(destinationChild, sourceHold)}`);
+		signal.throwIfAborted();
+		const runArgv = relaySsh(source.connection, [], rsyncClientCommand(argv, source.path, sourcePort));
+		const result = await runNative(wrap(runArgv), signal);
+		if (result.exit === 255) result.stderr = (result.stderr + relayDetail(destinationChild, sourceHold)).slice(-OUTPUT_LIMIT);
+		if (result.exit !== 0 && /remote port forwarding failed|administratively prohibited|could not request (local|remote) forwarding/.test(relayDetail(destinationChild, sourceHold))) throw new Error(`dual-SSH rsync forwarding route refused by an endpoint: ${relayDetail(destinationChild, sourceHold)}`);
+		return {
+			...result,
+			route: "ssh-ssh-forward",
+			cleanup: await settle(),
+			sshArgv: [
+				destinationArgv,
+				sourceHoldArgv,
+				runArgv
+			]
+		};
+	} catch (error) {
+		await settle().catch(() => "unknown");
+		if (signal.aborted) throw signal.reason;
+		const detail = relayDetail(destinationChild, sourceHold);
+		if (detail) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`${message}${message.includes("[relay stderr]") ? "" : detail}`, { cause: error });
+		}
+		throw error;
+	} finally {
+		await Promise.allSettled([destinationChild.stop(), sourceHold.stop()]);
+	}
+}
+function relayDetail(...held) {
+	const detail = held.map((child) => child.stderrSink.text).filter(Boolean).join("\n");
+	return detail ? `\n[relay stderr]\n${detail}` : "";
+}
+function daemonCommand(targetPath, port) {
+	if (/[\r\n]/.test(targetPath)) throw new Error("dual-SSH rsync refuses newline-bearing destination paths (no daemon config injection)");
+	return `set -eu
+[ -d ${shellQuote(targetPath)} ] || { echo 'dual-SSH rsync destination directory does not exist' >&2; exit 64; }
+umask 077
+tmp=$(mktemp -d "\${TMPDIR:-/tmp}/superd-rsync.XXXXXXXX")
+# The origin reads this marker from held stderr and stops the daemon + removes
+# the directory over a dedicated cleanup session: killing the local ssh cannot
+# rely on remote traps (a dropped connection terminates the remote session
+# without HUP), and an unreaped daemon keeps its loopback port open.
+printf 'SUPERD-RSYNC-TMP %s\\n' "$tmp" >&2
+printf '%s\\n' 'use chroot = no' 'read only = no' 'munge symlinks = yes' 'hosts allow = 127.0.0.1' 'hosts deny = *' 'pid file = '"$tmp"'/rsyncd.pid' '[task]' ${shellQuote("path = " + targetPath)} > "$tmp/rsyncd.conf"
+exec rsync --daemon --no-detach --address=127.0.0.1 --port=${port} --config="$tmp/rsyncd.conf"
+`;
+}
+/** Best-effort teardown of the remote daemon (pidfile kill) and its temp dir
+* over its own SSH session; identities stay origin-held. Returns whether the
+* whole teardown is confirmed. */
+async function removeRemoteTemp(connection, path$1, wrap) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), 1e4);
+	const script = `if [ -f ${shellQuote(path$1 + "/rsyncd.pid")} ]; then
+  p=$(cat ${shellQuote(path$1 + "/rsyncd.pid")})
+  kill "$p" 2>/dev/null || :
+  i=0; while kill -0 "$p" 2>/dev/null && [ "$i" -lt 20 ]; do sleep 0.1; i=$((i+1)); done
+  kill -9 "$p" 2>/dev/null || :
+fi
+rm -rf ${shellQuote(path$1)}`;
+	try {
+		return (await runNative(wrap(relaySsh(connection, [], script)), controller.signal)).exit === 0;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function rsyncClientCommand(argv, sourcePath, port) {
+	return `exec rsync ${argv.map(shellQuote).join(" ")} -- ${shellQuote(sourcePath)} rsync://127.0.0.1:${port}/task/`;
+}
+function shellQuote(value) {
+	return /[^A-Za-z0-9_@%+=:,./-]/.test(value) ? `'${value.replaceAll("'", `'\\''`)}'` : value;
+}
+/**
+* Route B (empirical verdict): a Node bidirectional bridge of two SSH exec
+* standard streams carrying one rsync protocol conversation. The design was
+* validated with local processes (source rsync client + fd-dup adapter +
+* `rsync --server --daemon .` receiver, full transfer with real delta), but
+* under real OpenSSH sessions the source-side combination (rsync client in an
+* exec session + fd-dup adapter) makes ssh tear down the session's stdin
+* channel ("channel 0: read failed ... Broken pipe" then EOF), starving the
+* protocol's return path before any byte of rsync protocol flows. Shell-level
+* adjustments (closing fd 0 for the client, dropping -T/keepalives) did not
+* change this on OpenSSH 10.2 + rsync 3.4.1. Per the spec this route reports
+* itself unavailable on such combinations instead of degrading into two
+* ordinary rsyncs or a full copy: the origin would stage the whole source and
+* the destination's existing data could not feed delta matching.
+*/
+async function stdioRoute(argv, source, destination, signal, options) {
+	signal.throwIfAborted();
+	throw new Error("dual-SSH rsync stdio route unavailable on this SSH/rsync combination: the source-side rsync client with a stdio adapter causes the SSH session stdin channel to be torn down before the rsync protocol starts (validated locally without SSH; fails under OpenSSH 10.2 + rsync 3.4.1). No full-copy fallback is performed");
+}
+
+//#endregion
+//#region src/remote/rsync.ts
+/**
+* Native rsync with ordered caller options. Local↔SSH runs rsync directly with
+* the endpoint's SSH identity wired as RSYNC_RSH; explicit -e/--rsh in argv
+* overrides that wiring per rsync's own rules (the receipt shows the argv).
+* SSH↔SSH delegates to the native relay routes (forwarding first, stdio second).
+* No option is injected: no archive, no timeout, no dry-run, no remote owner.
+*/
+async function runRsync(request, source, destination, signal, options = {}) {
+	signal.throwIfAborted();
+	checkAbsolute(source.path);
+	checkAbsolute(destination.path);
+	const argv = checkArgv("argv", request.argv);
+	if ("pullArgv" in request || "pushArgv" in request) throw new Error("remote: rsync takes argv only; pullArgv/pushArgv are copy-only fields");
+	for (const legacy of [
+		"dryRun",
+		"delete",
+		"excludes",
+		"preserve",
+		"verify",
+		"mkdir"
+	]) if (legacy in request) throw new Error(`remote: rsync field "${legacy}" was removed — pass native options through argv instead (e.g. "--dry-run", "--delete", "--exclude=<pattern>", "-a"/"-r"; verify/mkdir belong to the copy Hub/local lane)`);
+	if (!source.connection && !destination.connection) throw new Error("rsync requires at least one SSH endpoint; local-only is unsupported");
+	let result;
+	let route;
+	if (source.connection && destination.connection) {
+		const relayed = await relayRsync(argv, {
+			connection: source.connection,
+			path: source.path
+		}, {
+			connection: destination.connection,
+			path: destination.path
+		}, signal, options);
+		result = relayed;
+		route = relayed.route;
+	} else {
+		route = "local-ssh";
+		const remote = source.connection ?? destination.connection;
+		const wrap = options.wrapArgv ?? ((value) => value);
+		const callerRsh = argv.some((token) => token === "-e" || token === "--rsh" || token.startsWith("--rsh=") || /^-[a-zA-Z]+e$/.test(token) && !token.startsWith("--"));
+		const hostSpec = (connection) => {
+			const host = connection.host.includes(":") && !connection.host.startsWith("[") ? `[${connection.host}]` : connection.host;
+			return connection.user !== void 0 ? `${connection.user}@${host}` : host;
+		};
+		const env = callerRsh ? {} : { RSYNC_RSH: rsyncRsh(remote, wrap) };
+		const src = source.connection ? callerRsh ? `${hostSpec(source.connection)}:${source.path}` : `rsync-native:${source.path}` : source.path;
+		const dst = destination.connection ? callerRsh ? `${hostSpec(destination.connection)}:${destination.path}` : `rsync-native:${destination.path}` : destination.path;
+		result = await runNative(wrap([
+			"rsync",
+			...argv,
+			"--",
+			src,
+			dst
+		]), signal, env);
+	}
+	const number = (label) => {
+		const match = new RegExp(`^${label}: ([\\d,]+)(?: bytes)?$`, "m").exec(result.stdout);
+		return match ? Number(match[1].replaceAll(",", "")) : void 0;
+	};
+	const sentBytes = number("Total bytes sent"), receivedBytes = number("Total bytes received");
+	const literalBytes = number("Literal data"), matchedBytes = number("Matched data");
+	const itemized = result.stdout.split("\n").filter((line) => /^[<>ch.*][fdLDS.]/.test(line) || line.startsWith("*deleting"));
+	return {
+		...result,
+		action: "rsync",
+		src: request.src,
+		dst: request.dst,
+		argv,
+		route,
+		command: `rsync ${argv.join(" ")}`,
+		...itemized.length > 0 || argv.includes("--itemize-changes") || argv.includes("-i") ? { itemizedChanges: itemized } : {},
+		...literalBytes === void 0 ? {} : { literalBytes },
+		...matchedBytes === void 0 ? {} : { matchedBytes },
+		...sentBytes === void 0 ? {} : { sentBytes },
+		...receivedBytes === void 0 ? {} : { receivedBytes },
+		...sentBytes !== void 0 && receivedBytes !== void 0 ? { transferredBytes: sentBytes + receivedBytes } : {}
+	};
+}
+/** RSYNC_RSH value: rsync word-splits this string with its own quote
+* convention (single quotes, internal quotes doubled); the adapter drops the
+* placeholder host rsync appends and execs the canonical SSH argv. All tokens
+* are tool-built argv (identity options/aliases), never model text. */
+function rsyncRsh(connection, wrap) {
+	const args = [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-T"
+	];
+	if (connection.user !== void 0) args.push("-l", connection.user);
+	if (connection.port !== void 0) args.push("-p", String(connection.port));
+	if (connection.key !== void 0) args.push("-i", connection.key);
+	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
+	args.push("--", connection.host);
+	return [
+		"bash",
+		"-c",
+		`shift; exec ${wrap(args).map(rshQuote).join(" ")} "$@"`,
+		"rsync-rsh"
+	].map(rshQuote).join(" ");
+}
+/** rsync -e/RSYNC_RSH grammar: doubled quotes, not shell backslashes (rsync(1) --rsh). */
+const rshQuote = (value) => "'" + value.replaceAll("'", "''") + "'";
+
+//#endregion
+//#region src/remote/endpoints.ts
+function parseFileEndpoint(value) {
+	if (typeof value !== "string" || !value) throw new Error("file endpoint required");
+	if (value.startsWith("/")) {
+		checkAbsolute(value);
+		return { path: value };
+	}
+	const split = value.lastIndexOf(":/");
+	if (split < 1) throw new Error("file endpoint must be [target:]absolute/path");
+	const target = value.slice(0, split), path$1 = value.slice(split + 1);
+	checkAbsolute(path$1);
+	if (target.startsWith("byop:")) throw new Error("BYO-PTY has no binary file lane; select SSH/Docker/Incus/Hub");
+	return {
+		target,
+		path: path$1
+	};
+}
+
+//#endregion
+//#region src/remote/ssh-targets.ts
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const USER = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+const HOST = /^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?(?:[A-Za-z0-9_][A-Za-z0-9_.-]*|\[[A-Fa-f0-9:.]+\]|[A-Fa-f0-9:]+)$/;
+const JUMP = /^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?(?:[A-Za-z0-9_][A-Za-z0-9_.-]*|\[[A-Fa-f0-9:.]+\])(?::([0-9]+))?$/;
+function validateSshLabel(label) {
+	if (!LABEL.test(label)) throw new Error("[E_BAD_LABEL] remote: BYO-SSH label must use letters, digits, dot, underscore or hyphen and start with a letter/digit");
+}
+function bad(field) {
+	throw new Error(`[E_SSH_PARAMS] remote: invalid SSH ${field} — use host/user/port, an existing origin key file path, and optional ProxyJump aliases or [user@]host[:port] hops; no inline keys or shell options`);
+}
+function normalizeSshConnection(input) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) bad("connection");
+	if (Object.keys(input).some((key$1) => ![
+		"host",
+		"user",
+		"port",
+		"key",
+		"proxyJump"
+	].includes(key$1))) bad("field");
+	if (typeof input.host !== "string" || !HOST.test(input.host)) bad("host");
+	if (input.user !== void 0 && (typeof input.user !== "string" || !USER.test(input.user))) bad("user");
+	if (input.port !== void 0 && (!Number.isInteger(input.port) || input.port < 1 || input.port > 65535)) bad("port");
+	if (input.proxyJump !== void 0) {
+		if (typeof input.proxyJump !== "string" || !input.proxyJump || input.proxyJump.split(",").some((hop) => {
+			const match = JUMP.exec(hop);
+			return !match || match[1] !== void 0 && (Number(match[1]) < 1 || Number(match[1]) > 65535);
+		})) bad("proxyJump");
+	}
+	let key;
+	if (input.key !== void 0) {
+		if (typeof input.key !== "string" || !input.key || /[\0\r\n]/.test(input.key)) bad("key");
+		key = input.key.startsWith("~/") ? join(homedir(), input.key.slice(2)) : resolve(input.key);
+		try {
+			if (!statSync(key).isFile()) bad("key");
+		} catch {
+			bad("key file (must exist on the origin)");
+		}
+	}
+	return Object.freeze({
+		host: input.host,
+		...input.user === void 0 ? {} : { user: input.user },
+		...input.port === void 0 ? {} : { port: input.port },
+		...key === void 0 ? {} : { key },
+		...input.proxyJump === void 0 ? {} : { proxyJump: input.proxyJump }
 	});
-	clearTimers();
+}
+/** One instance per Agent-owned driver; destroyed with its Agent/plugin owners. */
+var SshTargets = class {
+	targets = /* @__PURE__ */ new Map();
+	register(label, connection) {
+		validateSshLabel(label);
+		const normalized = normalizeSshConnection(connection), existing = this.targets.get(label);
+		if (existing && JSON.stringify(existing) !== JSON.stringify(normalized)) throw new Error(`[E_LABEL_CONFLICT] remote: byossh:${label} SSH identity conflict — nothing was run. Reuse the label without ssh, or choose another label; existing credentials were not replaced`);
+		if (!existing) this.targets.set(label, normalized);
+		return existing ?? normalized;
+	}
+	get(label) {
+		validateSshLabel(label);
+		return this.targets.get(label);
+	}
+	entries() {
+		return [...this.targets.entries()];
+	}
+	clear() {
+		this.targets.clear();
+	}
+};
+/** Shared by execution, probes and file/relay consumers. extraArgs is trusted
+* internal SSH argv (e.g. forwarding), never a model-provided shell string. */
+function sshArgv(connection, options = {}) {
+	const args = options.tty ? [
+		"ssh",
+		"-tt",
+		"-o",
+		"BatchMode=yes"
+	] : [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-T"
+	];
+	if (connection.user !== void 0) args.push("-l", connection.user);
+	if (connection.port !== void 0) args.push("-p", String(connection.port));
+	if (connection.key !== void 0) args.push("-i", connection.key);
+	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
+	args.push(...options.extraArgs ?? [], "--", connection.host);
+	if (options.command !== void 0) args.push(options.command);
+	return args;
+}
+
+//#endregion
+//#region src/remote/input.ts
+/** Local carrier validation precedes any target discovery, connection or spawn. */
+async function prepareRemoteInput(input) {
+	if (input.mode !== void 0 && input.mode !== "oneshot" && input.mode !== "pty") throw new Error("[E_BAD_MODE] remote: mode must be oneshot or pty");
+	if (input.script !== void 0) {
+		if (input.cmd !== void 0 || input.stdin !== void 0 || input.mode === "pty" || input.spawn !== void 0 || input.target?.startsWith("byop:")) throw new Error("[E_SCRIPT_PARAMS] remote: script is oneshot-only and cannot be combined with cmd, stdin, spawn or BYO-PTY");
+		if (typeof input.script !== "string" || !isAbsolute(input.script) || input.script.includes("\0")) throw new Error("[E_SCRIPT_PATH] remote: script must be a local absolute path without NUL");
+	}
+	if (!input.target) throw new Error("[E_PARAMS] remote: target is required; spawn requires a byop:<label> target");
+	if (input.script !== void 0) {
+		let stdin;
+		try {
+			stdin = await readFile(input.script, "utf8");
+		} catch (error) {
+			throw new Error(`[E_SCRIPT_READ] remote: cannot read local script ${JSON.stringify(input.script)} — ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return {
+			target: input.target,
+			ssh: input.ssh,
+			cmd: "bash -s",
+			stdin,
+			mode: "oneshot",
+			timeout: input.timeout
+		};
+	}
 	return {
-		exit,
-		timedOut,
-		stdout,
-		stderr,
-		durationMs: Date.now() - started
+		target: input.target,
+		spawn: input.spawn,
+		ssh: input.ssh,
+		cmd: input.cmd ?? "",
+		stdin: input.stdin,
+		mode: input.mode,
+		timeout: input.timeout
 	};
 }
 
+//#endregion
+//#region src/remote/oneshot.ts
+async function runOneShot(argv, opts = {}) {
+	const process$1 = startOneShot(argv, opts);
+	const result = await process$1.done;
+	const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
+	return {
+		...result,
+		stdout: stdout.text,
+		stderr: [stderr.text, stderr.diagnostic].filter(Boolean).join("\n"),
+		outputStats: {
+			stdout: stdout.stats,
+			stderr: stderr.stats
+		}
+	};
+}
+
+//#endregion
+//#region src/remote/transports.ts
+/** POSIX 单引号机械转义（唯一一层转义，spec §三"一层机械转义"）。 */
+function shQuote(s) {
+	return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+/** One-shot（§五.1）：不分配 tty，收尾 = 子进程退出码，零字符串扫描。
+* POSIX wrapper（无远端 Python/owner/lease）：
+*  - wrapper 跑在 setsid 的私有会话里：sshd 会话进程与命令共享进程组，
+*    不隔离的话 kill 0 会把连接一起带走。
+*  - EXIT trap（自免疫后杀组）：命令正常结束时回收后台化子孙——它们不
+*    越过调用存活，也不会攥住 stdout 拖住收尾；退出码原样透传。
+*  - cleanupTag：远端把 wrapper 的 pgid 写进 pidfile；本地取消/超时后经
+*    独立清理会话按组 kill（与 rsync daemon 的远端清理同构——实证 sshd
+*    对无 PTY 会话断连不发信号，本地 killpg 杀不到远端）。 */
+function buildOneShotArgv(plan, cmd, options = {}) {
+	const tag = options.cleanupTag;
+	const wrapped = `${tag === void 0 ? "" : `printf '%s' "$(ps -o pgid= -p $$ | tr -d ' ')" > "\${TMPDIR:-/tmp}/superd-oneshot-${tag}.pgid"\n`}trap 'trap "" TERM HUP INT; kill -TERM 0 2>/dev/null; exit 143' TERM HUP INT
+trap 'trap "" TERM HUP INT; kill -TERM 0 2>/dev/null${tag === void 0 ? "" : `; rm -f "\${TMPDIR:-/tmp}/superd-oneshot-${tag}.pgid"`}' EXIT
+bash -lc ${shQuote(cmd)}`;
+	const sessioned = [
+		"setsid",
+		"--wait",
+		"bash",
+		"-c",
+		wrapped
+	];
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `setsid --wait bash -c ${shQuote(wrapped)}` });
+		case "docker": return [
+			"docker",
+			"exec",
+			"-i",
+			"--",
+			plan.container,
+			...sessioned
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			...sessioned
+		];
+	}
+}
+/** Persistent pty（Ruling 2）：ssh/incus 走宿主管道，docker 经 script(1) 托管宿主 PTY。 */
+function buildPtyArgv(plan) {
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, {
+			tty: true,
+			command: "bash"
+		});
+		case "docker": return [
+			"script",
+			"-qfec",
+			`stty -echo 2>/dev/null ; exec docker exec -it -- ${shQuote(plan.container)} bash`,
+			"/dev/null"
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-interactive",
+			plan.container,
+			"--",
+			"bash"
+		];
+	}
+}
+/** BYO-PTY（§三 spawn）：工具只提供 PTY 托管 + Nonce 注入 + 收帧。 */
+function buildSpawnArgv(spawnCommand) {
+	return [
+		"script",
+		"-qfec",
+		`stty -echo 2>/dev/null ; exec ${spawnCommand}`,
+		"/dev/null"
+	];
+}
+
 //#endregion
 //#region src/remote/nonce-framing.ts
 /** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
@@ -93,11 +1590,23 @@ function stripAnsi(s) {
 function normalizePtyText(s) {
 	return stripAnsi(s).replace(/\r\n/g, "\n").replace(/\r/g, "");
 }
-function tailWindow(text, cap) {
-	if (text.length <= cap) return { text };
+function tailWindow(text, cap, stats) {
+	let tail = text.slice(-cap);
+	if (tail.charCodeAt(0) >= 56320 && tail.charCodeAt(0) <= 57343) tail = tail.slice(1);
+	const returned = stats?.unit === "bytes" ? Buffer.byteLength(tail) : tail.length;
+	const total = stats?.total ?? text.length;
+	const updated = stats === void 0 ? {} : { stats: {
+		...stats,
+		returned
+	} };
+	if (total <= returned) return {
+		text: tail,
+		...updated
+	};
 	return {
-		text: `[truncated: showing last ${cap} of ${text.length} chars]\n${text.slice(text.length - cap)}`,
-		truncated: text.length
+		text: `[truncated: showing last ${returned} of ${total} ${stats?.unit === "bytes" ? "bytes" : "chars"}${stats !== void 0 && stats.dropped > 0 ? `; retained ${stats.retained}, dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === "bytes" ? "bytes" : "UTF-16 code units"}` : ""}]\n${tail}`,
+		truncated: total,
+		...updated
 	};
 }
 const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/;
@@ -182,6 +1691,9 @@ var PtySession = class {
 	lastSettleAt = 0;
 	/** 是否曾成功初始化（ready 过）。决定死亡语义：ready 过 → reconnect（留池）；从未 ready → 出池（见 start()）。 */
 	everReady = false;
+	disposal;
+	procClose = Promise.resolve();
+	groupCleanup = Promise.resolve();
 	constructor(opts) {
 		this.opts = opts;
 	}
@@ -207,16 +1719,17 @@ var PtySession = class {
 			const started = Date.now();
 			const reconnected = this.state === "dead";
 			if (this.state !== "ready") await this.start();
+			if (this.state === "disposed") throw new Error(`[E_SESSION_DISPOSED] remote pty session '${displayKey(this.opts.key)}' was disposed before dispatch`);
 			this.inFlight++;
 			return await new Promise((resolve$1) => {
 				const nonce = genNonce();
-				let output = "";
+				const ring = new Utf16TailRing(OUTPUT_HARD_CAP);
 				let interrupted = false;
 				let settled = false;
 				let interruptTimer;
 				let killTimer;
 				const deathWaiter = () => finish({
-					output,
+					output: ring.text,
 					exit: null,
 					cwd: null,
 					timedOut: interrupted
@@ -236,20 +1749,17 @@ var PtySession = class {
 					this.resetIdleTimer();
 					resolve$1({
 						...r,
+						outputStats: { stdout: ring.stats() },
 						reconnected,
 						durationMs: Date.now() - started
 					});
 				};
 				const parser = createNonceFrameParser(nonce, {
 					onOutput: (t) => {
-						output += t;
-						if (output.length > OUTPUT_HARD_CAP) {
-							output = output.slice(output.length - OUTPUT_HARD_CAP);
-							if (output.charCodeAt(0) >= 56320 && output.charCodeAt(0) <= 57343) output = output.slice(1);
-						}
+						ring.push(t);
 					},
 					onFrame: ({ exit, cwd }) => finish({
-						output,
+						output: ring.text,
 						exit,
 						cwd,
 						timedOut: interrupted
@@ -266,7 +1776,7 @@ var PtySession = class {
 						this.killTree();
 						this.markDead();
 						finish({
-							output,
+							output: ring.text,
 							exit: null,
 							cwd: null,
 							timedOut: true
@@ -281,14 +1791,24 @@ var PtySession = class {
 		return run;
 	}
 	/** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
-	async dispose() {
-		if (this.state === "disposed") return;
+	dispose() {
+		if (this.disposal) return this.disposal;
 		this.clearIdleTimer();
 		this.state = "disposed";
 		this.startPromise = null;
+		const proc = this.proc;
+		const close = this.procClose;
+		const group = this.reapGroup(proc?.pid, 1e3, close);
+		this.disposal = Promise.all([
+			close,
+			this.groupCleanup,
+			group
+		]).then(() => {
+			if (this.proc === proc) this.proc = null;
+		});
 		this.write("exit\n");
-		setTimeout(() => this.killTree(), 1e3).unref();
 		this.opts.onDead?.();
+		return this.disposal;
 	}
 	write(s) {
 		if (this.proc?.stdin?.writable !== true) return;
@@ -326,7 +1846,12 @@ var PtySession = class {
 		proc.stderr.setEncoding("utf8").on("data", (d) => {
 			this.diag = (this.diag + d).slice(-2e3);
 		});
-		proc.once("close", () => this.markDead());
+		this.procClose = new Promise((resolve$1) => {
+			proc.once("close", () => {
+				this.markDead();
+				resolve$1();
+			});
+		});
 		proc.once("error", (err) => {
 			this.diag = (this.diag + `\n[remote: spawn failed: ${err.message}]`).slice(-2e3);
 		});
@@ -374,6 +1899,7 @@ var PtySession = class {
 	}
 	resetIdleTimer() {
 		this.clearIdleTimer();
+		if (this.state === "disposed") return;
 		this.idleTimer = setTimeout(() => void this.dispose(), this.opts.idleTtlSec * 1e3);
 		this.idleTimer.unref();
 	}
@@ -386,20 +1912,69 @@ var PtySession = class {
 	killTree() {
 		const pid = this.proc?.pid;
 		this.proc = null;
-		if (pid === void 0) return;
-		try {
-			process.kill(-pid, "SIGTERM");
-		} catch {}
-		setTimeout(() => {
+		const cleanup = this.reapGroup(pid, 0, this.procClose);
+		this.groupCleanup = Promise.all([this.groupCleanup, cleanup]).then(() => void 0);
+	}
+	/** A direct child's close is not proof that its detached process group is gone. */
+	reapGroup(pid, graceMs, close) {
+		if (pid === void 0) return Promise.resolve();
+		const signal = (value) => {
 			try {
-				process.kill(-pid, "SIGKILL");
-			} catch {}
-		}, 2e3).unref();
+				process.kill(-pid, value);
+				return true;
+			} catch (error) {
+				if (error.code === "ESRCH") return false;
+				throw error;
+			}
+		};
+		return new Promise((resolve$1, reject) => {
+			let termTimer;
+			let killTimer;
+			let settled = false;
+			const finish = (error) => {
+				if (settled) return;
+				settled = true;
+				if (termTimer !== void 0) clearTimeout(termTimer);
+				if (killTimer !== void 0) clearTimeout(killTimer);
+				if (error !== void 0) reject(error);
+				else resolve$1();
+			};
+			const checkGone = () => {
+				try {
+					if (!signal(0)) finish();
+				} catch (error) {
+					finish(error);
+				}
+			};
+			checkGone();
+			if (settled) return;
+			close.then(checkGone);
+			termTimer = setTimeout(() => {
+				try {
+					if (!signal("SIGTERM")) {
+						finish();
+						return;
+					}
+					killTimer = setTimeout(() => {
+						try {
+							signal("SIGKILL");
+							killTimer = setTimeout(() => finish(), 100);
+						} catch (error) {
+							finish(error);
+						}
+					}, 2e3);
+				} catch (error) {
+					finish(error);
+				}
+			}, graceMs);
+		});
 	}
 };
 /** 会话池：键 → 会话。意外死亡的会话留在池内（下次 dispatch 带 reconnect 提示）。 */
 var PtyPool = class {
 	sessions = /* @__PURE__ */ new Map();
+	disposed = false;
+	disposal;
 	constructor(defaults) {
 		this.defaults = defaults;
 	}
@@ -424,6 +1999,7 @@ var PtyPool = class {
 		return s === void 0 || s.sessionState === "disposed" ? void 0 : s;
 	}
 	getOrCreate(key, argv, origin) {
+		if (this.disposed) throw new Error("[E_REMOTE_DISPOSED] remote: the owning Agent or plugin PTY pool was disposed");
 		let s = this.sessions.get(key);
 		if (s === void 0 || s.sessionState === "disposed") {
 			s = new PtySession({
@@ -437,9 +2013,12 @@ var PtyPool = class {
 		}
 		return s;
 	}
-	async disposeAll() {
-		await Promise.all([...this.sessions.values()].map((s) => s.dispose()));
-		this.sessions.clear();
+	disposeAll() {
+		if (this.disposal) return this.disposal;
+		this.disposed = true;
+		return this.disposal = Promise.all([...this.sessions.values()].map((s) => s.dispose())).then(() => {
+			this.sessions.clear();
+		});
 	}
 };
 
@@ -489,17 +2068,10 @@ async function probeTarget(plan, opts = {}) {
 	const hard = opts.hardTimeoutSec ?? 10;
 	const runner = opts.runner ?? runOneShot;
 	const started = Date.now();
-	const r = await runner(plan.kind === "ssh" ? [
-		"ssh",
-		"-o",
-		"BatchMode=yes",
-		"-o",
-		`ConnectTimeout=${ct}`,
-		"-T",
-		"--",
-		plan.host,
-		"true"
-	] : plan.kind === "docker" ? [
+	const r = await runner(plan.kind === "ssh" ? sshArgv(plan.connection ?? { host: plan.host }, {
+		extraArgs: ["-o", `ConnectTimeout=${ct}`],
+		command: "true"
+	}) : plan.kind === "docker" ? [
 		"docker",
 		"inspect",
 		"--format",
@@ -677,6 +2249,7 @@ async function renderRoster(sessions, opts = {}) {
 	} catch (error) {
 		lines.push(`ssh hosts: no readable ~/.ssh/config (${error instanceof Error ? error.message : String(error)})`);
 	}
+	lines.push(`byossh labels (this Agent, in memory): ${opts.byosshLabels?.map((label) => `byossh:${label}`).join(", ") || "(none)"}`);
 	const docker = await runner([
 		"docker",
 		"ps",
@@ -710,91 +2283,21 @@ async function renderRoster(sessions, opts = {}) {
 	return lines.join("\n");
 }
 
-//#endregion
-//#region src/remote/transports.ts
-/** POSIX 单引号机械转义（唯一一层转义，spec §三"一层机械转义"）。 */
-function shQuote(s) {
-	return `'${s.replaceAll("'", `'\\''`)}'`;
-}
-/** One-shot（§五.1）：不分配 tty，收尾 = 子进程退出码，零字符串扫描。 */
-function buildOneShotArgv(plan, cmd) {
-	switch (plan.kind) {
-		case "ssh": return [
-			"ssh",
-			"-o",
-			"BatchMode=yes",
-			"-T",
-			"--",
-			plan.host,
-			`bash -lc ${shQuote(cmd)}`
-		];
-		case "docker": return [
-			"docker",
-			"exec",
-			"-i",
-			"--",
-			plan.container,
-			"bash",
-			"-lc",
-			cmd
-		];
-		case "incus": return [
-			"incus",
-			"exec",
-			"--force-noninteractive",
-			plan.container,
-			"--",
-			"bash",
-			"-lc",
-			cmd
-		];
-	}
-}
-/** Persistent pty（Ruling 2）：ssh/incus 走宿主管道，docker 经 script(1) 托管宿主 PTY。 */
-function buildPtyArgv(plan) {
-	switch (plan.kind) {
-		case "ssh": return [
-			"ssh",
-			"-tt",
-			"-o",
-			"BatchMode=yes",
-			"--",
-			plan.host,
-			"bash"
-		];
-		case "docker": return [
-			"script",
-			"-qfec",
-			`stty -echo 2>/dev/null ; exec docker exec -it -- ${shQuote(plan.container)} bash`,
-			"/dev/null"
-		];
-		case "incus": return [
-			"incus",
-			"exec",
-			"--force-interactive",
-			plan.container,
-			"--",
-			"bash"
-		];
-	}
-}
-/** BYO-PTY（§三 spawn）：工具只提供 PTY 托管 + Nonce 注入 + 收帧。 */
-function buildSpawnArgv(spawnCommand) {
-	return [
-		"script",
-		"-qfec",
-		`stty -echo 2>/dev/null ; exec ${spawnCommand}`,
-		"/dev/null"
-	];
-}
-
 //#endregion
 //#region src/remote/driver.ts
 /** PTY label 字符集：只禁空白 / `:` / 控制字符（roster 一行一 label，带换行的 label 渲染即烂）。 */
 const PTY_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /** 双轨调度器（spec §七 Phase 2）：参数校验 → 路由 → oneshot 子进程 / pty 会话池。 */
 var RemoteDriver = class {
+	sshTargets = new SshTargets();
 	pool;
+	hubOwner = randomUUID();
+	hubProviders = /* @__PURE__ */ new Set();
+	processes = /* @__PURE__ */ new Set();
+	starting = /* @__PURE__ */ new Set();
+	fileAbort = new AbortController();
+	disposed = false;
+	disposal;
 	constructor(opts = {}) {
 		this.opts = opts;
 		this.pool = new PtyPool({ idleTtlSec: opts.idleTtlSec ?? 600 });
@@ -802,11 +2305,14 @@ var RemoteDriver = class {
 	async call(params, callCtx = {}) {
 		const started = Date.now();
 		try {
-			const routing = this.route(params);
-			const result = await this.execute(params, routing, callCtx);
+			this.assertOpen();
+			const prepared = await prepareRemoteInput(params);
+			this.assertOpen();
+			const routing = this.route(prepared);
+			const result = await this.execute(prepared, routing, callCtx);
 			this.audit({
 				target: routing.display,
-				cmd: params.cmd,
+				cmd: prepared.cmd,
 				cwd: result.cwd ?? void 0,
 				exit: result.exit,
 				durationMs: Date.now() - started
@@ -815,13 +2321,196 @@ var RemoteDriver = class {
 		} catch (error) {
 			this.audit({
 				target: params.target ?? params.spawn ?? "?",
-				cmd: params.cmd,
+				cmd: params.cmd ?? "[local script]",
 				error: error instanceof Error ? error.message : String(error),
 				durationMs: Date.now() - started
 			});
 			throw error;
 		}
 	}
+	/** Native-first copy routing (spec: remote-native-shortcut): CLI peers run
+	* their native CLI verbatim; only Hub↔local↔local stays on the staged tree
+	* lane with verify/mkdir. Mixed pairs (Hub↔CLI peer) are refused: Hub has no
+	* native CLI and the tree lane has no CLI options. */
+	copy(request, signal, callCtx = {}) {
+		const combined = AbortSignal.any([signal, this.fileAbort.signal]);
+		const work = (async () => {
+			this.assertOpen();
+			combined.throwIfAborted();
+			const resolve$1 = async (value) => {
+				const parsed = parseFileEndpoint(value);
+				if (!parsed.target) return {
+					kind: "local",
+					path: parsed.path
+				};
+				if (parsed.target.startsWith("hub:")) return {
+					kind: "hub",
+					path: parsed.path,
+					machine: parsed.target.slice(4)
+				};
+				const plan = await this.resolveConnectionTarget(parsed.target, callCtx);
+				this.assertOpen();
+				combined.throwIfAborted();
+				return {
+					kind: "cli",
+					path: parsed.path,
+					plan
+				};
+			};
+			const src = await resolve$1(request.src), dst = await resolve$1(request.dst);
+			this.assertOpen();
+			combined.throwIfAborted();
+			if (src.kind === "hub" || dst.kind === "hub") {
+				if (src.kind === "hub" && dst.kind === "local") {
+					const hub = this.requireHub();
+					this.hubProviders.add(hub);
+					return copyTree(request, {
+						path: src.path,
+						endpoint: hub.fileEndpoint(src.machine)
+					}, {
+						path: dst.path,
+						endpoint: localFileEndpoint()
+					}, combined);
+				}
+				if (src.kind === "local" && dst.kind === "hub") {
+					const hub = this.requireHub();
+					this.hubProviders.add(hub);
+					return copyTree(request, {
+						path: src.path,
+						endpoint: localFileEndpoint()
+					}, {
+						path: dst.path,
+						endpoint: hub.fileEndpoint(dst.machine)
+					}, combined);
+				}
+				if (src.kind === "hub" && dst.kind === "hub") {
+					const hub = this.requireHub();
+					this.hubProviders.add(hub);
+					return copyTree(request, {
+						path: src.path,
+						endpoint: hub.fileEndpoint(src.machine)
+					}, {
+						path: dst.path,
+						endpoint: hub.fileEndpoint(dst.machine)
+					}, combined);
+				}
+				throw new Error("copy: Hub endpoints pair only with local paths or another Hub machine (native CLI peers have no Hub lane and the Hub has no CLI options)");
+			}
+			if (src.kind === "local" && dst.kind === "local") return copyTree(request, {
+				path: src.path,
+				endpoint: localFileEndpoint()
+			}, {
+				path: dst.path,
+				endpoint: localFileEndpoint()
+			}, combined);
+			if (request.verify !== void 0 || request.mkdir !== void 0) throw new Error("copy: verify/mkdir apply to the Hub/local staged lane only; native CLI routes do not verify or create parents (mirror the CLI's own behavior with argv like -r)");
+			const planOf = (end) => end.kind === "cli" ? end.plan : end.kind === "local" ? { kind: "local" } : void 0;
+			const srcPlan = planOf(src), dstPlan = planOf(dst);
+			if (srcPlan === void 0 || dstPlan === void 0) throw new Error("copy: unreachable route resolution");
+			return nativeCopy({
+				src: request.src,
+				dst: request.dst,
+				...request.argv === void 0 ? {} : { argv: request.argv },
+				...request.pullArgv === void 0 ? {} : { pullArgv: request.pullArgv },
+				...request.pushArgv === void 0 ? {} : { pushArgv: request.pushArgv }
+			}, {
+				src: {
+					plan: srcPlan,
+					path: src.path
+				},
+				dst: {
+					plan: dstPlan,
+					path: dst.path
+				}
+			}, combined, { wrapArgv: this.opts.nativeArgvFor });
+		})();
+		this.starting.add(work);
+		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
+		return work;
+	}
+	rsync(request, signal, callCtx = {}) {
+		const combined = AbortSignal.any([signal, this.fileAbort.signal]);
+		const work = (async () => {
+			this.assertOpen();
+			combined.throwIfAborted();
+			const endpoint = async (value) => {
+				const parsed = parseFileEndpoint(value);
+				if (!parsed.target) return { path: parsed.path };
+				if (/^(hub|docker|incus|byop):/.test(parsed.target)) throw new Error("rsync supports SSH/byossh only (plus one local endpoint); no mixed-transport or copy fallback");
+				const plan = await this.resolveConnectionTarget(parsed.target, callCtx);
+				this.assertOpen();
+				combined.throwIfAborted();
+				if (plan.kind !== "ssh") throw new Error("rsync requires an SSH target; no copy fallback");
+				return {
+					path: parsed.path,
+					connection: plan.connection ?? { host: plan.host }
+				};
+			};
+			const source = await endpoint(request.src), destination = await endpoint(request.dst);
+			this.assertOpen();
+			combined.throwIfAborted();
+			return runRsync(request, source, destination, combined, { wrapArgv: this.opts.nativeArgvFor });
+		})();
+		this.starting.add(work);
+		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
+		return work;
+	}
+	/** Only called from JobSpec.run: admission precedes local file reads and discovery. */
+	start(input, signal) {
+		const work = this.startPrepared(input, AbortSignal.any([signal, this.fileAbort.signal]));
+		this.starting.add(work);
+		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
+		return work;
+	}
+	async startPrepared(input, signal) {
+		this.assertOpen();
+		signal.throwIfAborted();
+		const params = await prepareRemoteInput(input);
+		this.assertOpen();
+		signal.throwIfAborted();
+		const route = this.route(params);
+		if (route.mode !== "oneshot" || route.pty) throw new Error("remote: background requires oneshot");
+		let process$1;
+		if (route.display.startsWith("hub:")) {
+			const hub = this.requireHub();
+			this.hubProviders.add(hub);
+			process$1 = await hub.start(route.display.slice(4), {
+				...params,
+				mode: "oneshot"
+			}, this.hubOwner);
+		} else {
+			const plan = route.plan ?? await this.resolveBareName(route.bare, "no-session", false);
+			this.assertOpen();
+			signal.throwIfAborted();
+			if (plan.kind === "pty") throw new Error("remote: background requires oneshot");
+			process$1 = await this.nativeProcess(plan, params, params.timeout, signal);
+		}
+		this.own(process$1);
+		if (signal.aborted || this.disposed) process$1.cancel("owner closed during start");
+		return process$1;
+	}
+	nativeProcess(plan, params, timeoutSec, signal = this.fileAbort.signal) {
+		const cleanupTag = randomUUID().slice(0, 8);
+		const process$1 = startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, params.cmd, { cleanupTag }), {
+			stdin: params.stdin,
+			timeoutSec
+		});
+		process$1.done.then((result) => {
+			if (!result.cancelled && !result.timedOut) return;
+			const pidfile = `"\${TMPDIR:-/tmp}/superd-oneshot-${cleanupTag}.pgid"`;
+			const cleanup = `p=$(cat ${pidfile} 2>/dev/null) && { kill -TERM -- "-$p" 2>/dev/null; sleep 0.3; kill -KILL -- "-$p" 2>/dev/null; }; rm -f ${pidfile}`;
+			startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, cleanup, {}), { timeoutSec: 15 }).done.catch(() => {});
+		}).catch(() => {});
+		const work = Promise.resolve(process$1);
+		this.starting.add(work);
+		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
+		return work;
+	}
+	own(process$1) {
+		this.processes.add(process$1);
+		process$1.done.then(() => this.processes.delete(process$1));
+		return process$1;
+	}
 	/** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
 	/**
 	* Ruling P20 + PTY 候选表末位：裸名按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
@@ -831,13 +2520,15 @@ var RemoteDriver = class {
 	async resolveBareName(name$1, sessionKey, usePtyLabels = true) {
 		const runner = this.opts.rosterRunner ?? runOneShot;
 		const readCfg = this.opts.sshConfigReader ?? (async () => await readFile(join(homedir(), ".ssh", "config"), "utf8"));
+		let hosts = [];
 		try {
-			const { hosts } = literalHosts(await readCfg());
-			if (hosts.some((h) => h.toLowerCase() === name$1.toLowerCase())) return {
-				kind: "ssh",
-				host: name$1
-			};
+			hosts = literalHosts(await readCfg()).hosts;
 		} catch {}
+		this.assertOpen();
+		if (hosts.some((h) => h.toLowerCase() === name$1.toLowerCase())) return {
+			kind: "ssh",
+			host: name$1
+		};
 		const docker = await runner([
 			"docker",
 			"ps",
@@ -845,6 +2536,7 @@ var RemoteDriver = class {
 			"--format",
 			"{{.Names}}"
 		], { timeoutSec: 10 });
+		this.assertOpen();
 		if (docker.exit === 0 && docker.stdout.trim().split(/\r?\n/).some((n) => n.trim().toLowerCase() === name$1.toLowerCase())) return {
 			kind: "docker",
 			container: name$1
@@ -857,6 +2549,7 @@ var RemoteDriver = class {
 			"--columns",
 			"n"
 		], { timeoutSec: 10 });
+		this.assertOpen();
 		if (incus.exit === 0 && incus.stdout.trim().split(/\r?\n/).some((n) => n.split(",")[0]?.trim().toLowerCase() === name$1.toLowerCase())) return {
 			kind: "incus",
 			container: name$1
@@ -875,22 +2568,47 @@ var RemoteDriver = class {
 	*  而活会话是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，且两个 agent 各开一条线
 	*  的代价可忽略。BYO-PTY 天然是活的，于是自然落进这个 scope，无需另立规则。 */
 	async roster(callCtx = {}) {
+		this.assertOpen();
 		const prefix = `${callCtx.sessionKey ?? "no-session"}|`;
-		return await renderRoster(this.pool.list().filter(({ key }) => key.startsWith(prefix)).map(({ key, snapshot }) => ({
+		const sessions = this.pool.list().filter(({ key }) => key.startsWith(prefix)).map(({ key, snapshot }) => ({
 			target: displayKey(key),
 			state: snapshot.state,
 			idleSec: snapshot.idleMs !== null ? Math.round(snapshot.idleMs / 1e3) : null
-		})), this.opts.rosterRunner !== void 0 ? { runner: this.opts.rosterRunner } : {});
+		}));
+		const runner = this.opts.rosterRunner ?? runOneShot;
+		const hub = this.opts.getHub?.();
+		return [...hub ? ["hub machines: " + (hub.listTargets().map((t) => `hub:${t.id} (${t.label}${t.execEnabled ? "" : "; exec disabled"})`).join(", ") || "none")] : [], await renderRoster(sessions, {
+			byosshLabels: this.sshTargets.entries().map(([label]) => label),
+			readSshConfig: this.opts.sshConfigReader,
+			runner: (argv, options) => {
+				this.assertOpen();
+				return runner(argv, options);
+			}
+		})].join("\n");
 	}
 	async status(target, callCtx = {}) {
+		this.assertOpen();
+		if (target.startsWith("hub:")) {
+			const machine = target.slice(4);
+			const row = this.requireHub().listTargets().find((t) => t.id === machine);
+			if (!row) throw new Error(`unknown remote machine ${machine} — select a remote machine from the Hub roster; local execution is not available`);
+			return `${target} — Hub remote machine (${row.label}); exec ${row.execEnabled ? "enabled" : "disabled"}; not probed`;
+		}
 		const sessionKey = callCtx.sessionKey ?? "no-session";
 		const label = target.startsWith("byop:") ? target.slice(5) : void 0;
 		if (label !== void 0) return this.ptyStatus(target, label, sessionKey);
-		const resolved = /^(docker|incus|ssh):/.test(target) ? resolveTarget(target) : await this.resolveBareName(target, sessionKey);
+		const direct = /^(docker|incus|ssh):/.test(target);
+		const resolved = target.startsWith("byossh:") ? this.byosshPlan(target) : direct ? resolveTarget(target) : await this.resolveBareName(target, sessionKey);
+		this.assertOpen();
 		if (resolved.kind === "pty") return this.ptyStatus(`byop:${resolved.label}`, resolved.label, sessionKey);
+		const head = `${target} — ${resolved.kind === "ssh" ? "ssh host" : `${resolved.kind} container`}`;
+		const runner = this.opts.probeRunner ?? runOneShot;
 		return [
-			`${target} — ${resolved.kind === "ssh" ? "ssh host" : `${resolved.kind} container`}`,
-			renderProbe(await probeTarget(resolved, { runner: this.opts.probeRunner })),
+			head,
+			renderProbe(await probeTarget(resolved, { runner: (argv, options) => {
+				this.assertOpen();
+				return runner(argv, options);
+			} })),
 			renderSession(this.pool.inspect(`${sessionKey}|t:${target}`))
 		].join("\n");
 	}
@@ -904,12 +2622,50 @@ var RemoteDriver = class {
 			this.opts.onAudit?.(r);
 		} catch {}
 	}
+	/** Registration never dials; response reveals labels only, not credentials. */
+	registerSsh(target, connection) {
+		this.assertOpen();
+		if (!target.startsWith("byossh:")) throw new Error("[E_SSH_PARAMS] remote: ssh requires a byossh:<label> target");
+		this.sshTargets.register(target.slice(7), connection);
+		return `${target} registered (no dialing). Reuse this Agent's label without ssh; a new Agent/cold resume must register again.`;
+	}
+	byosshPlan(target, connection) {
+		if (connection !== void 0) this.registerSsh(target, connection);
+		const spec = this.sshTargets.get(target.slice(7));
+		if (!spec) throw new Error(`[E_NO_SSH_TARGET] remote: ${target} is not registered in this Agent — supply ssh:{host,user?,port?,key?,proxyJump?} first; key must be an existing origin file path`);
+		return {
+			kind: "ssh",
+			host: spec.host,
+			connection: spec
+		};
+	}
+	/** Single target resolver for later copy/rsync; BYO identities cannot be
+	* independently re-resolved through the origin's alias table. */
+	async resolveConnectionTarget(target, callCtx = {}) {
+		this.assertOpen();
+		if (target.startsWith("byossh:")) return this.byosshPlan(target);
+		if (/^(docker|incus|ssh):/.test(target)) return resolveTarget(target);
+		if (/^(byop|hub):/.test(target)) throw new Error("remote: select an SSH/Docker/Incus target for this connection resolver");
+		const plan = await this.resolveBareName(target, callCtx.sessionKey ?? "no-session", false);
+		this.assertOpen();
+		if (plan.kind === "pty") throw new Error("remote: BYO-PTY is not a filesystem connection");
+		return plan;
+	}
 	route(params) {
 		const hasTarget = params.target !== void 0 && params.target.length > 0;
 		const hasSpawn = params.spawn !== void 0 && params.spawn.length > 0;
 		if (!hasTarget && !hasSpawn) throw new Error("[E_PARAMS] remote: target is required (e.g. { target: \"dev4\", cmd: \"git status\" }); spawn is a modifier of a \"byop:<label>\" target and cannot stand alone");
 		if (params.timeout !== void 0 && (!Number.isFinite(params.timeout) || params.timeout <= 0)) throw new Error(`[E_BAD_TIMEOUT] remote: timeout must be a positive number of seconds (got ${JSON.stringify(params.timeout)})`);
 		if (params.stdin !== void 0 && (params.cmd === void 0 || params.cmd.length === 0)) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd");
+		if (params.ssh !== void 0 && !params.target.startsWith("byossh:")) throw new Error("[E_SSH_PARAMS] remote: ssh requires a byossh:<label> target");
+		if (params.target.startsWith("byossh:")) {
+			if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn is only for byop:<label>, not BYO-SSH");
+			return {
+				mode: params.mode ?? "oneshot",
+				display: params.target,
+				plan: this.byosshPlan(params.target, params.ssh)
+			};
+		}
 		if (hasTarget && params.target.startsWith("byop:")) {
 			const label = params.target.slice(5);
 			if (!PTY_LABEL_RE.test(label)) throw new Error(`[E_BAD_LABEL] remote: PTY label must match ${PTY_LABEL_RE.source} (got ${JSON.stringify(label)}) — e.g. target: "byop:dev3"`);
@@ -925,6 +2681,10 @@ var RemoteDriver = class {
 		}
 		if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn requires a \"byop:<label>\" target — e.g. { target: \"byop:dev3\", spawn: \"ssh dev3\", cmd: \"…\" }; it is not a standalone entry point");
 		const mode = params.mode ?? "oneshot";
+		if (params.target.startsWith("hub:")) return {
+			mode,
+			display: params.target
+		};
 		const direct = /^(docker|incus|ssh):/.test(params.target);
 		return {
 			mode,
@@ -933,25 +2693,82 @@ var RemoteDriver = class {
 		};
 	}
 	async execute(params, routing, callCtx) {
+		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
+		const cap = this.opts.maxOutputChars ?? 3e4;
+		if (routing.display.startsWith("hub:")) {
+			const hub = this.requireHub();
+			this.hubProviders.add(hub);
+			const machine = routing.display.slice(4);
+			if (routing.mode === "pty") {
+				const result$1 = await hub.pty(machine, params.cmd, this.hubOwner, {
+					stdin: params.stdin,
+					timeout: timeoutSec
+				});
+				const out$2 = tailWindow(result$1.stdout, cap, result$1.outputStats?.stdout);
+				return {
+					...result$1,
+					stdout: out$2.text,
+					...out$2.stats ? { outputStats: {
+						...result$1.outputStats,
+						stdout: out$2.stats
+					} } : {},
+					...out$2.truncated === void 0 ? {} : { truncated: out$2.truncated }
+				};
+			}
+			const process$1 = this.own(await hub.start(machine, {
+				...params,
+				target: routing.display,
+				mode: "oneshot",
+				timeout: timeoutSec
+			}, this.hubOwner));
+			if (this.disposed) process$1.cancel("owner disposed");
+			const result = await process$1.done;
+			const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
+			const out$1 = tailWindow(stdout.text, cap, stdout.stats);
+			const err = tailWindow(stderr.text, cap, stderr.stats);
+			return {
+				...result,
+				mode: "oneshot",
+				target: routing.display,
+				cwd: null,
+				reconnected: false,
+				stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out$1.text,
+				stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
+				...out$1.stats ? { outputStats: {
+					stdout: out$1.stats,
+					stderr: err.stats
+				} } : { outputStatsUnavailable: true },
+				...out$1.truncated === void 0 ? {} : { truncated: out$1.truncated }
+			};
+		}
 		const sessionKey = callCtx.sessionKey ?? "no-session";
 		if (routing.bare !== void 0) {
 			const resolved = await this.resolveBareName(routing.bare, sessionKey, params.mode !== "oneshot");
+			this.assertOpen();
 			if (resolved.kind === "pty") {
 				routing.pty = { label: resolved.label };
 				routing.mode = "pty";
 				routing.display = `byop:${resolved.label}`;
 			} else routing.plan = resolved;
 		}
-		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
-		const cap = this.opts.maxOutputChars ?? 3e4;
 		if (routing.pty !== void 0) return await this.ptyCall(routing.pty, params, sessionKey, timeoutSec, cap);
 		if (routing.mode === "oneshot") {
-			const r$1 = await runOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(routing.plan, params.cmd), {
-				stdin: params.stdin,
-				timeoutSec
-			});
-			const out$1 = tailWindow(r$1.stdout, cap);
-			const err = r$1.stderr.length > 0 ? tailWindow(r$1.stderr, cap) : void 0;
+			this.assertOpen();
+			const process$1 = this.own(await this.nativeProcess(routing.plan, params, timeoutSec));
+			if (this.disposed) process$1.cancel("owner disposed");
+			const result = await process$1.done;
+			const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
+			const r$1 = {
+				...result,
+				stdout: stdout.text,
+				stderr: [stderr.text, stderr.diagnostic].filter(Boolean).join("\n"),
+				outputStats: {
+					stdout: stdout.stats,
+					stderr: stderr.stats
+				}
+			};
+			const out$1 = tailWindow(r$1.stdout, cap, r$1.outputStats?.stdout);
+			const err = r$1.stderr.length > 0 ? tailWindow(r$1.stderr, cap, r$1.outputStats?.stderr) : void 0;
 			return {
 				mode: "oneshot",
 				target: routing.display,
@@ -961,6 +2778,10 @@ var RemoteDriver = class {
 				reconnected: false,
 				stdout: out$1.text,
 				...err !== void 0 ? { stderr: err.text } : {},
+				...out$1.stats ? { outputStats: {
+					stdout: out$1.stats,
+					stderr: err?.stats ?? r$1.outputStats?.stderr
+				} } : {},
 				durationMs: r$1.durationMs,
 				...out$1.truncated !== void 0 ? { truncated: out$1.truncated } : {}
 			};
@@ -971,7 +2792,7 @@ var RemoteDriver = class {
 			stdin: params.stdin,
 			timeoutSec
 		});
-		const out = tailWindow(r.output, cap);
+		const out = tailWindow(r.output, cap, r.outputStats?.stdout);
 		return {
 			mode: "pty",
 			target: routing.display,
@@ -980,6 +2801,7 @@ var RemoteDriver = class {
 			timedOut: r.timedOut,
 			reconnected: r.reconnected,
 			stdout: out.text,
+			outputStats: out.stats ? { stdout: out.stats } : void 0,
 			durationMs: r.durationMs,
 			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
 		};
@@ -1001,7 +2823,7 @@ var RemoteDriver = class {
 			stdin: params.stdin,
 			timeoutSec
 		});
-		const out = tailWindow(r.output, cap);
+		const out = tailWindow(r.output, cap, r.outputStats?.stdout);
 		return {
 			mode: "pty",
 			target: display,
@@ -1012,27 +2834,200 @@ var RemoteDriver = class {
 			reconnected: r.reconnected,
 			stdout: out.text,
 			...notice !== void 0 ? { notice } : {},
+			outputStats: out.stats ? { stdout: out.stats } : void 0,
 			durationMs: r.durationMs,
 			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
 		};
 	}
-	async dispose() {
-		await this.pool.disposeAll();
+	hasHub() {
+		return this.opts.getHub?.() !== void 0;
+	}
+	requireHub() {
+		this.assertOpen();
+		const hub = this.opts.getHub?.();
+		if (!hub || hub.protocol !== 1) throw new Error("[E_HUB_UNAVAILABLE] remote: Hub transport unavailable — enable the Super D Hub body, or select an explicit SSH/Docker/Incus/BYO target");
+		return hub;
+	}
+	assertOpen() {
+		if (this.disposed) throw new Error("[E_REMOTE_DISPOSED] remote: this Agent or plugin owner has exited — create a new session or cold resume");
+	}
+	dispose() {
+		if (this.disposal) return this.disposal;
+		this.sshTargets.clear();
+		this.disposed = true;
+		this.fileAbort.abort(/* @__PURE__ */ new Error("remote owner disposed"));
+		for (const process$1 of this.processes) process$1.cancel("remote owner disposed");
+		return this.disposal = (async () => {
+			await Promise.allSettled([...this.starting]);
+			await Promise.all([
+				this.pool.disposeAll(),
+				...[...this.processes].map((p) => p.done),
+				...[...this.hubProviders].map((hub) => hub.releaseOwner(this.hubOwner))
+			]);
+			this.hubProviders.clear();
+		})();
 	}
 };
 
+//#endregion
+//#region src/remote/jobs.ts
+/** No preparation or discovery before the official registry's admission. */
+function startRemoteJob(registry, input, exec, driver) {
+	if (input.mode === "pty" || input.spawn !== void 0 || input.target?.startsWith("byop:")) throw new Error("remote: background execution requires oneshot; PTY and BYO-PTY are unsupported");
+	if (!exec.agent) throw new Error("remote: background jobs require a live Agent owner");
+	let process$1;
+	const output = ["stdout", "stderr"].map((channel) => ({
+		channel,
+		read: (fromByte) => {
+			const read = process$1?.read(channel, fromByte);
+			return read ? {
+				text: read.text,
+				nextOffset: read.nextOffset,
+				lossy: read.lossy
+			} : {
+				text: "",
+				nextOffset: fromByte,
+				lossy: false
+			};
+		}
+	}));
+	return registry.start({
+		kind: "remote",
+		owner: exec.agent.id,
+		label: `${input.target}: ${input.cmd ?? input.script}`,
+		output,
+		run() {
+			const controller = new AbortController();
+			return {
+				done: (async () => {
+					try {
+						process$1 = await driver.start({
+							...input,
+							mode: "oneshot"
+						}, controller.signal);
+						if (controller.signal.aborted) process$1.cancel(controller.signal.reason);
+						const result = await process$1.done;
+						const diagnostic = process$1.read("stderr", 0).diagnostic;
+						return {
+							status: controller.signal.aborted || result.cancelled ? "killed" : diagnostic ? "failed" : result.timedOut ? "killed" : "completed",
+							detail: diagnostic ?? (result.timedOut ? "timeout" : `exit code: ${result.exit}`)
+						};
+					} catch (error) {
+						return {
+							status: controller.signal.aborted ? "killed" : "failed",
+							detail: error instanceof Error ? error.message : String(error)
+						};
+					}
+				})(),
+				cancel(reason) {
+					if (controller.signal.aborted) return;
+					controller.abort(reason);
+					process$1?.cancel(reason);
+				}
+			};
+		}
+	});
+}
+
 //#endregion
 //#region src/remote/tool.ts
 const NO_SESSION_KEY = "remote:no-session";
+/**
+* The model-visible surface of the `remote` tool. Kept as ONE template
+* literal so it can be edited here directly — no string concatenation and no
+* apostrophe escaping. Plain text only: no backticks and no "${" inside.
+*/
+const REMOTE_TOOL_DESCRIPTION = `Remote execution and file transfer over ssh / docker / incus, plus persistent named shells. Pick the call shape:
+  {}                       → roster (local scan, no dialing)
+  {target}                 → status probe: reachable / unreachable — <native error>, or container state + session layer
+  {target, cmd}            → run cmd — oneshot by default; mode "pty" for a persistent shell
+  {target, script:"/abs"}  → LOCAL script over stdin to a fixed bash -s (oneshot only; no cmd/stdin/spawn/mode mix)
+  {target:"byossh:lbl", ssh:{host,user?,port?,key?,proxyJump?}} → register this Agent's SSH identity (no cmd = register only); reuse the target later with ssh omitted. Same spec idempotent; different spec refused — use another label. key is an existing origin file, never inline material; nothing written or persisted; a new Agent registers again.
+  {target:"byop:lbl", spawn, cmd} → create the named shell once; reuse as {target:"byop:lbl", cmd} (no spawn)
+Bare names resolve ssh config → docker → incus → live pty; unmatched goes to ssh and its native error surfaces. Prefixes ssh: / docker: / incus: / byop: force a channel. byop: same spawn repeated is reused; a different spawn is refused ([E_LABEL_CONFLICT], nothing runs); unknown or idle-expired → [E_NO_SESSION] (spawn is not retained — pass it again); a failed spawn frees the label.
+
+oneshot: stateless bash -lc, stdout/stderr separate, exit code verbatim; the endpoint needs bash only (no Python). A POSIX wrapper reaps backgrounded children on completion and kills the whole group on timeout/cancel — they never outlive the call or hold the channel. pty: one shell per (agent, target); cwd/env survive, streams merge, Ctrl-C interrupts without killing, idle reap after 600s.
+
+Files — {action:"copy" | "rsync", src:"[target:]abs", dst:"[target:]abs", argv:["-a"]}: argv tokens pass verbatim before src/dst — no whitelist, no forced defaults (dry run = pass "--dry-run" yourself); the CLI's own exit code and stderr come back in the receipt. copy: local↔SSH scp; SSH↔SSH scp -3 through the origin (identities stay local); docker cp; incus file push/pull; any other pair = two commands with origin staging (per-half options via pullArgv/pushArgv, exclusive with argv); scp -R refused; success is NOT independently verified; verify/mkdir only on the Hub↔local lane. rsync: local↔SSH, or SSH↔SSH with one protocol conversation between the peers (real delta; forwarding denied → honest error, never full copy). rsync src trailing slash copies contents, no slash the directory itself.
+
+Output: pty tails at ~30k chars ("[truncated: …]" header) — redirect bulk output to a file. Hard retention 4,000,000 UTF-16 units per stream (Hub 4MiB bytes); outputStats reports the rest; restart cannot recover discarded output. stdin feeds the command; timeout (seconds) interrupts then kills. run_in_background:true (oneshot) → jobId for job_output/job_kill. Native transport errors pass through verbatim — self-correct from them.`;
 function createRemoteTool(driver, opts = {}) {
 	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
-	return defineTool({
+	const tool = defineTool({
 		name: "remote",
-		description: "Remote execution over three transports (ssh / docker / incus) plus named persistent BYO shells. Pick the call shape first:\n  {}                                 → roster: known target names from a local scan (no dialing)\n  {target}                           → on-demand status probe of that one target (for \"byop:<label>\": its session state)\n  {target, cmd}                      → run cmd — oneshot by default; mode \"pty\" for a persistent shell\n  {target:\"byop:<label>\", spawn, cmd} → BYO-PTY: create the persistent shell you named <label>\n  {target:\"byop:<label>\", cmd}        → reuse that shell (spawn is only needed to create)\nBYO-PTY labels are yours to choose, and the label alone is the whole reuse mechanism: \"byop:dev3\" is created once with `spawn` (the command that starts an interactive shell, e.g. \"docker exec -it img bash\"), and from then on you address it as {target:\"byop:dev3\", cmd} with no spawn. Repeating the same spawn for a live label is reused and the result tells you to drop it; repeating a *different* spawn is refused with [E_LABEL_CONFLICT] and nothing runs — reuse the label, or pick a new one. A label that was never created, or was reaped after the idle TTL, answers [E_NO_SESSION]: spawn is not retained, so pass it again to re-create. A spawn that fails to come up (e.g. a bad host) leaves nothing behind either — the label stays free, so just retry with a corrected spawn. Bare names match in order — ssh config, then docker, then incus, then a live pty label (on a collision the earlier source wins; a name matching none of them goes to ssh and its native error surfaces). \"byop:<label>\" / \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a channel when you must be explicit. oneshot: stateless `bash -lc`, stdout/stderr separate, the exit code is the remote process's own. pty: one persistent shell per (agent, target) — cwd/env survive across calls, streams merge, Ctrl-C interrupts without killing the session, idle sessions are reaped after 600s (a reconnect notice precedes the fresh shell). Output is tail-truncated at ~30k chars with a \"[truncated: …]\" header — redirect bulk output to a file yourself. `stdin` feeds the command; `timeout` (seconds) interrupts then kills. Native transport errors pass through verbatim — self-correct from them. Background processes must redirect their own output (`cmd > log 2>&1 &`). Status probes report \"reachable\"/\"unreachable — <native error>\" or the factual container state plus the session layer (\"idle Ns\" / \"busy\" / \"none — dials on first exec\"), always probed at call time.",
+		description: REMOTE_TOOL_DESCRIPTION,
 		parameters: {
+			action: {
+				type: "string",
+				enum: ["copy", "rsync"],
+				description: "Optional file action; omit for execution/status/roster."
+			},
+			src: {
+				type: "string",
+				description: "copy/rsync source [target:]absolute path; rsync retains trailing-slash semantics"
+			},
+			dst: {
+				type: "string",
+				description: "copy/rsync destination [target:]absolute path"
+			},
+			argv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Ordered native CLI options and values for one-command routes (e.g. rsync [\"-a\",\"--partial\",\"--dry-run\"], scp [\"-p\"], docker cp [\"-a\"], incus file push/pull). One element = one argv token, appended verbatim before src/dst; no shell parsing, no whitelist, no forced defaults — unknown options fail in the native CLI itself. rsync only (SSH endpoints): explicit -e/--rsh overrides the tool's SSH wiring. Two-segment cross-endpoint copy uses pullArgv/pushArgv instead."
+			},
+			pullArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
+			},
+			pushArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PUSH half (origin staging → destination endpoint) of a two-command cross-endpoint copy. Mutually exclusive with argv; must be paired with pullArgv. Only options valid for the push half's CLI."
+			},
+			verify: {
+				type: "boolean",
+				description: "copy only, Hub↔local↔local staged lane only: independent SHA-256 verification (default true). Native CLI routes do not verify and report that fact."
+			},
+			mkdir: {
+				type: "boolean",
+				description: "copy only, Hub↔local↔local staged lane only: create missing destination parents (default true). Native CLI routes let the CLI decide."
+			},
+			run_in_background: {
+				type: "boolean",
+				description: "Oneshot only: return a native jobId immediately, read with job_output, cancel with job_kill; output is available while running. Requires official jobs service/controller."
+			},
 			target: {
 				type: "string",
-				description: "Single entry point. Bare name / IP / domain matches in order: ssh config, then docker, then incus, then a live pty label (a collision goes to the earlier source). \"byop:<label>\" / \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a channel. For \"byop:<label>\", pass spawn the first time to create it and omit spawn afterwards to reuse it. Omit cmd → status probe."
+				description: "Single entry point. byossh:<label> reuses this Agent-scoped registered SSH identity (pass ssh on first call; no cmd registers only). Bare name / IP / domain matches in order: ssh config, then docker, then incus, then a live pty label (a collision goes to the earlier source). \"byop:<label>\" / \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a channel. For \"byop:<label>\", pass spawn the first time to create it and omit spawn afterwards to reuse it. Omit cmd → status probe."
+			},
+			ssh: {
+				type: "object",
+				description: "Only for byossh:<label>: register origin-side connection; omit on reuse. No inline keys or arbitrary SSH options.",
+				additionalProperties: false,
+				properties: {
+					host: {
+						type: "string",
+						required: true,
+						description: "SSH hostname, IP or native config alias."
+					},
+					user: {
+						type: "string",
+						description: "Login user; omitted preserves native SSH config."
+					},
+					port: {
+						type: "integer",
+						description: "SSH port 1–65535; omitted preserves native SSH config."
+					},
+					key: {
+						type: "string",
+						description: "Existing origin private-key file path, not key contents; never copied or persisted."
+					},
+					proxyJump: {
+						type: "string",
+						description: "Official ProxyJump: comma-separated [user@]host[:port] or native aliases; jump identity remains in origin SSH config."
+					}
+				}
 			},
 			spawn: {
 				type: "string",
@@ -1042,6 +3037,10 @@ function createRemoteTool(driver, opts = {}) {
 				type: "string",
 				description: "One raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Omit with target → status probe; omit everything → roster."
 			},
+			script: {
+				type: "string",
+				description: "LOCAL absolute script path. Read before any dialing, sent literally over stdin to fixed bash -s. Oneshot only; cannot combine with cmd, stdin, spawn, pty mode or byop target. Hub inline cmd remains limited to 4096; script body is not argv."
+			},
 			mode: {
 				type: "string",
 				enum: ["oneshot", "pty"],
@@ -1067,13 +3066,18 @@ function createRemoteTool(driver, opts = {}) {
 						enum: [
 							"exec",
 							"status",
-							"roster"
+							"roster",
+							"job",
+							"copy",
+							"rsync"
 						]
 					},
 					text: {
 						type: "string",
 						required: true
 					},
+					jobId: { type: "string" },
+					receipt: { type: "json" },
 					exit: { oneOf: [{ type: "integer" }, { type: "null" }] },
 					durationMs: { type: "integer" },
 					cwd: { type: "string" },
@@ -1081,6 +3085,8 @@ function createRemoteTool(driver, opts = {}) {
 					timedOut: { type: "boolean" },
 					reconnected: { type: "boolean" },
 					truncated: { type: "integer" },
+					outputStats: { type: "json" },
+					outputStatsUnavailable: { type: "boolean" },
 					session: { type: "string" },
 					notice: { type: "string" }
 				}
@@ -1091,13 +3097,105 @@ function createRemoteTool(driver, opts = {}) {
 			}]
 		},
 		async execute(args, exec) {
+			if (args.action === "copy" || args.action === "rsync") {
+				if (!args.src || !args.dst) throw new Error(`${args.action} requires src and dst absolute endpoints`);
+				if ([
+					args.cmd,
+					args.script,
+					args.stdin,
+					args.spawn,
+					args.ssh,
+					args.target,
+					args.mode,
+					args.timeout,
+					args.run_in_background
+				].some((value) => value !== void 0)) throw new Error(`${args.action} cannot be combined with execution/PTY/job arguments; register byossh separately first`);
+				for (const legacy of [
+					"dryRun",
+					"delete",
+					"excludes",
+					"preserve"
+				]) if (args[legacy] !== void 0) throw new Error(`${legacy} was removed: pass native options through argv instead (e.g. ${legacy === "dryRun" ? "\"--dry-run\"" : legacy === "delete" ? "\"--delete\"" : legacy === "excludes" ? "\"--exclude=<pattern>\"" : "\"-a\" / \"-r\""})`);
+				if (args.action === "rsync") {
+					if (args.pullArgv !== void 0 || args.pushArgv !== void 0) throw new Error("rsync takes argv only; pullArgv/pushArgv are copy-only fields");
+					if ([args.verify, args.mkdir].some((value) => value !== void 0)) throw new Error("rsync cannot be combined with copy verify/mkdir options; the Hub/local staged lane is copy-only");
+					const start = Date.now();
+					const receipt$1 = await driver.rsync({
+						src: args.src,
+						dst: args.dst,
+						...args.argv === void 0 ? {} : { argv: args.argv }
+					}, exec.signal, { sessionKey: getSessionKey(exec) });
+					if (receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
+					return {
+						kind: "rsync",
+						text: JSON.stringify(receipt$1),
+						receipt: receipt$1,
+						exit: receipt$1.exit,
+						durationMs: Date.now() - start
+					};
+				}
+				const receipt = await driver.copy({
+					src: args.src,
+					dst: args.dst,
+					...args.verify === void 0 ? {} : { verify: args.verify },
+					...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
+					...args.argv === void 0 ? {} : { argv: args.argv },
+					...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
+					...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
+				}, exec.signal, { sessionKey: getSessionKey(exec) });
+				return {
+					kind: "copy",
+					text: JSON.stringify(receipt),
+					receipt,
+					exit: null,
+					durationMs: 0
+				};
+			}
+			if ([
+				args.src,
+				args.dst,
+				args.argv,
+				args.pullArgv,
+				args.pushArgv,
+				args.verify,
+				args.mkdir
+			].some((value) => value !== void 0)) throw new Error("file fields require action copy or rsync");
 			const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
 			const hasTarget = typeof args.target === "string" && args.target.length > 0;
 			const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
 			if (args.mode !== void 0 && args.mode !== "oneshot" && args.mode !== "pty") throw new Error(`[E_BAD_MODE] remote: mode must be 'oneshot' or 'pty' (got ${JSON.stringify(args.mode)})`);
-			if (!hasCmd) {
+			if (args.ssh !== void 0 && (!args.target?.startsWith("byossh:") || hasSpawn)) throw new Error("[E_SSH_PARAMS] remote: ssh requires a byossh:<label> target; spawn is only for byop:<label>");
+			if (args.run_in_background) {
+				if (!hasCmd && args.script === void 0) throw new Error("remote: background requires cmd or script");
+				if (args.mode === "pty" || hasSpawn || args.target?.startsWith("byop:")) throw new Error("remote: background requires oneshot; PTY and BYO-PTY are unsupported");
+				const jobs = exec.agent?.ctx.get("jobs");
+				if (!jobs) throw new Error("remote: background requires the official DSH jobs service and job_output/job_kill controller; foreground execution remains available");
+				const jobId = startRemoteJob(jobs, {
+					target: args.target,
+					cmd: args.cmd,
+					script: args.script,
+					ssh: args.ssh,
+					stdin: args.stdin,
+					mode: "oneshot",
+					timeout: args.timeout
+				}, exec, driver);
+				return {
+					kind: "job",
+					jobId,
+					text: `Started ${jobId}. Use job_output to read and job_kill to cancel; completion is reported by the host.`,
+					exit: null,
+					durationMs: 0
+				};
+			}
+			if (!hasCmd && args.script === void 0) {
 				if (args.stdin !== void 0) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd — status probes take no input");
 				if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn is an exec channel — pass cmd (there is nothing to probe for BYO-PTY)");
+				if (args.ssh !== void 0) return {
+					kind: "status",
+					text: driver.registerSsh(args.target, args.ssh),
+					exit: null,
+					durationMs: 0
+				};
 				if (!hasTarget) return {
 					kind: "roster",
 					text: await driver.roster({ sessionKey: getSessionKey(exec) }),
@@ -1114,7 +3212,9 @@ function createRemoteTool(driver, opts = {}) {
 			const r = await driver.call({
 				target: args.target,
 				spawn: args.spawn,
+				ssh: args.ssh,
 				cmd: args.cmd,
+				script: args.script,
 				mode: args.mode === "oneshot" || args.mode === "pty" ? args.mode : void 0,
 				stdin: args.stdin,
 				timeout: args.timeout
@@ -1130,14 +3230,22 @@ function createRemoteTool(driver, opts = {}) {
 			if (r.timedOut) v.timedOut = true;
 			if (r.reconnected) v.reconnected = true;
 			if (r.truncated !== void 0) v.truncated = r.truncated;
+			if (r.outputStats !== void 0) v.outputStats = r.outputStats;
+			if (r.outputStatsUnavailable) v.outputStatsUnavailable = true;
 			if (r.session !== void 0) v.session = r.session;
 			if (r.notice !== void 0) v.notice = r.notice;
 			return v;
 		}
 	});
+	const description = tool.description;
+	Object.defineProperty(tool, "description", {
+		enumerable: true,
+		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self). {} includes the Hub directory even when empty. Uses authenticated Hub HTTP oneshot / persistent WS PTY; no SSH alias needed. Hub failures never fall back to SSH." : "")
+	});
+	return tool;
 }
 function renderValue(v) {
-	if (v.kind === "status" || v.kind === "roster") return v.text;
+	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "copy" || v.kind === "rsync") return v.text;
 	const parts = [];
 	if (v.reconnected === true) parts.push(RECONNECT_NOTICE);
 	if (typeof v.notice === "string" && v.notice.length > 0) parts.push(v.notice);
@@ -1145,7 +3253,8 @@ function renderValue(v) {
 	const secs = ((v.durationMs ?? 0) / 1e3).toFixed(1);
 	const markers = [];
 	if (v.timedOut === true) markers.push("interrupted");
-	if (v.truncated !== void 0) markers.push(`truncated, original ${v.truncated} chars`);
+	if (v.truncated !== void 0) markers.push(`truncated, ${v.outputStatsUnavailable ? "returned peer tail" : "original"} ${v.truncated} ${v.outputStats?.stdout.unit === "bytes" ? "bytes" : "chars"}`);
+	if (v.outputStatsUnavailable) markers.push("peer output totals/retention unavailable; returned tail only");
 	const suffix = markers.length > 0 ? ` · ${markers.join(" · ")}` : "";
 	const cwdTag = typeof v.cwd === "string" && v.cwd.length > 0 ? ` · cwd ${v.cwd}` : "";
 	const sessionTag = typeof v.session === "string" && v.session.length > 0 ? ` · ${v.session}` : "";
@@ -1154,6 +3263,84 @@ function renderValue(v) {
 	return parts.join("\n");
 }
 
+//#endregion
+//#region src/remote/agent-registration.ts
+/** Host listeners attempt once per official creation edge, never on vacancy. */
+function installAgentRemote(ctx, config) {
+	return ctx.on("agent/created", ({ agent }) => {
+		const tools = agent.ctx.get("tools");
+		if (!tools) return;
+		const driver = new RemoteDriver({
+			...config,
+			getHub: () => agent.ctx.get("superdRemoteTransport")
+		});
+		let unregister;
+		try {
+			unregister = tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id }));
+		} catch (error) {
+			driver.dispose();
+			if (error instanceof Error && error.message === "tool \"remote\" is already registered in this scope" && tools.get("remote", agent) !== void 0) return;
+			throw error;
+		}
+		const stopService = agent.ctx.on("internal/service", (name$1) => {
+			if (name$1 === "superdRemoteTransport") agent.ctx.emit("tools/change");
+		});
+		let disposal;
+		let ownerUndo;
+		let agentUndo;
+		const cleanup = () => {
+			if (disposal) return disposal;
+			disposal = driver.dispose();
+			unregister();
+			stopService();
+			ownerUndo?.();
+			agentUndo?.();
+			return disposal;
+		};
+		agentUndo = agent.ctx.effect(() => cleanup, "remote.agentOwner()");
+		ownerUndo = ctx.effect(() => cleanup, "remote.rowOwner()");
+	});
+}
+
+//#endregion
+//#region src/remote/file-worker.ts
+async function runFileWorker(request) {
+	const abort = new AbortController(), cancel = () => abort.abort(/* @__PURE__ */ new Error("binary file worker cancelled"));
+	process.on("SIGTERM", cancel);
+	process.on("SIGHUP", cancel);
+	const report = (value) => new Promise((resolve$1, reject) => process.stderr.write(JSON.stringify(value) + "\n", (error) => error ? reject(error) : resolve$1()));
+	try {
+		mkdirSync(request.root, { mode: 448 });
+		const endpoint = localFileEndpoint({
+			receiveRoot: request.root,
+			temporary: (path$1, active) => report({
+				temporary: path$1,
+				active
+			})
+		});
+		if (request.action === "export") await pipeline(await endpoint.exportTree(request.path, abort.signal), process.stdout, { signal: abort.signal });
+		else if (request.action === "import") await endpoint.importTree(request.path, process.stdin, {
+			mkdir: request.mkdir,
+			signal: abort.signal
+		});
+		else {
+			let metadata = "";
+			process.stdin.setEncoding("utf8");
+			for await (const chunk of process.stdin) {
+				metadata += String(chunk);
+				if (Buffer.byteLength(metadata) > FILE_MAX_METADATA) throw new Error("file selection metadata limit exceeded");
+			}
+			process.stdout.write(JSON.stringify(await endpoint.digest(request.path, abort.signal, request.selected ? JSON.parse(metadata) : void 0)));
+		}
+	} catch (error) {
+		await report({ error: error instanceof Error ? error.message : String(error) }).catch(() => {});
+		process.exitCode = 1;
+	} finally {
+		process.removeListener("SIGTERM", cancel);
+		process.removeListener("SIGHUP", cancel);
+	}
+}
+
 //#endregion
 //#region src/remote/plugin.ts
 const name = "dashr-remote";
@@ -1169,15 +3356,7 @@ const Config = Schema.object({
 });
 /** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
 const apply = (ctx, config) => {
-	const driver = new RemoteDriver({
-		execTimeoutSec: config.execTimeoutSec,
-		idleTtlSec: config.idleTtlSec,
-		maxOutputChars: config.maxOutputChars
-	});
-	ctx.inject(["tools"], (toolsCtx) => {
-		toolsCtx.tools.register(createRemoteTool(driver, { getSessionKey: (exec) => exec.agent?.id ?? "remote:no-session" }));
-	});
-	return () => void driver.dispose();
+	return installAgentRemote(ctx, config);
 };
 var plugin_default = {
 	name,
@@ -1187,4 +3366,4 @@ var plugin_default = {
 };
 
 //#endregion
-export { Config, apply, plugin_default as default, inject, name };
+export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, SshTargets, Utf16TailRing, apply, checkAbsolute, checkSelection, plugin_default as default, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };