better-dsh 0.3.1-a → 0.3.1-d

package/lib/remote/plugin.js

@@ -1,12 +1,13 @@
-import { t as Schema } from "../lib-C8_jXvwA.js";
+import { t as Schema } from "../lib.js";
 import { Context } from "@deepseek-ai/cordis";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { constants, createReadStream, createWriteStream, mkdirSync, statSync } from "node:fs";
+import { constants, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 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 { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { createConnection, createServer } from "node:net";
@@ -317,17 +318,18 @@ async function copyTree(request, source, destination, signal, scratchRoot = join
 	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",
+		route: "hub-staged",
 		src: request.src,
 		dst: request.dst,
-		verified: false,
+		ok: false,
+		verification: "not-applicable",
 		bytes: 0,
 		entries: 0,
 		scope: "transferred entries"
 	};
+	const scratch = await mkdtemp(join(scratchRoot, "remote-copy-")), payload = join(scratch, "payload.bin");
 	try {
 		await pipeline(await source.endpoint.exportTree(source.path, signal), createWriteStream(payload, {
 			flags: "wx",
@@ -351,24 +353,79 @@ async function copyTree(request, source, destination, signal, scratchRoot = join
 			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;
+			receipt.verification = "sha256";
 		}
 		signal.throwIfAborted();
 		await rm(scratch, {
 			recursive: true,
 			force: true
 		});
+		receipt.ok = true;
 		return receipt;
 	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const reason = signal.aborted ? "aborted" : /mismatch/i.test(message) ? "digest-mismatch" : "staging-error";
 		throw new CopyError({
 			...receipt,
-			verified: false,
+			ok: false,
+			reason,
 			scratch,
-			error: error instanceof Error ? error.message : String(error)
+			error: message
 		});
 	}
 }
 
+//#endregion
+//#region src/remote/ssh-argv.ts
+/**
+* ONE identity-assembly policy for every SSH-speaking lane (user close-out
+* ruling 2026-10-17: "four builders necessarily mean four identity
+* semantics" — the structural root of F1).
+*
+* Assembly: explicit connection fields (byossh registrations; caller options
+* may override later by the CLI's own last-option-wins) in ONE order —
+* user, port, key, proxyJump — spoken in the target CLI's dialect.
+*
+* Resolution: config-side identity (aliases, config-only IdentityFile paths)
+* is read from the ORIGIN's own ssh config natively by every lane. The single
+* exception is the scp -3 temp config (ssh -F sees no user config), where
+* tempSshConfig inlines the `ssh -G`-resolved fields — paths only, never key
+* material (F1, 2026-10-14). That policy lives beside this builder in
+* native-copy.ts and must stay the only such inline site.
+*
+* Former duplicate builders now reduced here: sshArgv (execution/probes),
+* identityArgv (scp routes), rsyncRsh (RSYNC_RSH wiring), relaySsh
+* (dual-SSH relay). Behavior is byte-identical to each former site.
+*/
+/** Identity options ONLY for one connection, in the target CLI's dialect:
+* user, port, key, proxyJump — conditional, one order, NO base flags (each
+* lane's dialect base — BatchMode, -T, hardening — stays at its call site).
+* scp carries the user inside its user@host operand, so the scp dialect
+* never emits -l; its port flag is -P. */
+function sshIdentityArgv(connection, dialect) {
+	const args = [];
+	if (dialect === "ssh" && connection.user !== void 0) args.push("-l", connection.user);
+	if (connection.port !== void 0) args.push(dialect === "scp" ? "-P" : "-p", String(connection.port));
+	if (connection.key !== void 0) args.push("-i", connection.key);
+	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
+	return args;
+}
+/** Full ssh invocation around the shared identity core. base and extra are
+* trusted internal argv (dialect flags incl. BatchMode, forwarding options)
+* — never a model-provided shell string. */
+function sshCommandArgv(connection, base, extra, command) {
+	const args = [
+		"ssh",
+		...base,
+		...sshIdentityArgv(connection, "ssh"),
+		...extra,
+		"--",
+		connection.host
+	];
+	if (command !== void 0) args.push(command);
+	return args;
+}
+
 //#endregion
 //#region src/remote/output-ring.ts
 const continuation = (byte) => (byte & 192) === 128;
@@ -674,15 +731,17 @@ 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). */
+/** Connection identity as scp options, placed BEFORE caller argv so an
+* explicit caller -F/-i/-P/-J overrides the registered identity by scp's own
+* precedence (last option wins). Assembly itself lives in ssh-argv.ts
+* (the ONE identity policy — 2026-10-17 ruling); only the scp dialect
+* placement rule is local. */
 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;
+	return [
+		"-o",
+		"BatchMode=yes",
+		...sshIdentityArgv(connection, "scp")
+	];
 }
 function sshEndpoint(plan) {
 	if (plan.kind !== "ssh") throw new Error("remote: native copy endpoint is not an SSH target");
@@ -721,24 +780,30 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 		stdout: [],
 		stderr: [],
 		outputTruncated: false,
-		verified: false,
+		verification: "native-exit-only",
+		ok: true,
 		cleanup: "none-required"
 	};
-	const finish = (route, argvs, results) => {
+	const finish = (route, argvs, results, internal = []) => {
 		receipt.route = route;
-		receipt.argv = argvs;
+		receipt.argv = argvs.map((argv) => argv.map((token) => internal.find(([secret]) => secret === token)?.[1] ?? token));
 		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);
+		receipt.ok = !signal.aborted && receipt.exits.every((exit) => exit === 0);
+		if (!receipt.ok) receipt.reason = signal.aborted ? "aborted" : "non-zero-exit";
 		return receipt;
 	};
+	if (request.mkdir !== false) await ensureDestinationDir(endpoints.dst, signal, options.execArgvFor, wrap, receipt);
+	else receipt.created = "n-a";
 	if (s === "local" && t === "ssh") {
 		rejectRemoteToRemoteScp(oneShot);
 		const connection = sshEndpoint(endpoints.dst.plan).connection;
 		const argv = [
 			"scp",
 			...identityArgv(connection),
+			...await recursiveFlag(endpoints.src.path, oneShot, "-r"),
 			...oneShot,
 			endpoints.src.path,
 			scpSpec(connection, endpoints.dst.path)
@@ -771,7 +836,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 				dstSpec = scpSpec(destination, endpoints.dst.path);
 				extra = identityArgv(source);
 			} else {
-				config = await tempSshConfig(source, destination);
+				config = await tempSshConfig(source, destination, runNative);
 				extra = ["-F", config.path];
 				srcSpec = `superd-scp3-source:${endpoints.src.path}`;
 				dstSpec = `superd-scp3-destination:${endpoints.dst.path}`;
@@ -784,7 +849,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 				srcSpec,
 				dstSpec
 			];
-			return finish("scp -3 (data through origin)", [argv], [await runNative(wrap(argv), signal)]);
+			return finish("scp-3", [argv], [await runNative(wrap(argv), signal)], config !== void 0 ? [[config.path, "<temp-ssh-config>"]] : []);
 		} catch (error) {
 			if (signal.aborted) unknown = true;
 			throw error;
@@ -803,7 +868,9 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 			endpoints.src.path,
 			`${containerOf(endpoints.dst.plan)}:${endpoints.dst.path}`
 		];
-		return finish("docker cp", [argv], [await runNative(wrap(argv), signal)]);
+		const result = await runNative(wrap(argv), signal);
+		withSymlinkHint(result);
+		return finish("docker-cp", [argv], [result]);
 	}
 	if (s === "docker" && t === "local") {
 		const argv = [
@@ -813,18 +880,21 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 			`${containerOf(endpoints.src.plan)}:${endpoints.src.path}`,
 			endpoints.dst.path
 		];
-		return finish("docker cp", [argv], [await runNative(wrap(argv), signal)]);
+		const result = await runNative(wrap(argv), signal);
+		withSymlinkHint(result);
+		return finish("docker-cp", [argv], [result]);
 	}
 	if (s === "local" && t === "incus") {
 		const argv = [
 			"incus",
 			"file",
 			"push",
+			...await recursiveFlag(endpoints.src.path, oneShot, "-r"),
 			...oneShot,
 			endpoints.src.path,
 			`${containerOf(endpoints.dst.plan)}${endpoints.dst.path}`
 		];
-		return finish("incus file push", [argv], [await runNative(wrap(argv), signal)]);
+		return finish("incus-file-push", [argv], [await runNative(wrap(argv), signal)]);
 	}
 	if (s === "incus" && t === "local") {
 		const argv = [
@@ -835,7 +905,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 			`${containerOf(endpoints.src.plan)}${endpoints.src.path}`,
 			endpoints.dst.path
 		];
-		return finish("incus file pull", [argv], [await runNative(wrap(argv), signal)]);
+		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;
@@ -848,9 +918,12 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 		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]);
+		if (first.exit !== 0) {
+			receipt.note = "push not started: pull failed";
+			return finish("staged-pull-push", [pullArgv], [first], [[staged, "<staging>"]]);
+		}
 		const second = await runNative(wrap(pushArgv), signal);
-		return finish("two native commands with origin staging", [pullArgv, pushArgv], [first, second]);
+		return finish("staged-pull-push", [pullArgv, pushArgv], [first, second], [[staged, "<staging>"]]);
 	} finally {
 		receipt.cleanup = await rm(scratch, {
 			recursive: true,
@@ -911,40 +984,162 @@ function segmentArgv(plan, remote, staged, opts, leg) {
 		spec
 	];
 }
+/** D3 mkdir pre-hop: ensure the destination's PARENT directory exists before
+* the transfer (never the operand itself — see parent-only note below).
+* transfer. Local dst is node-side; remote dst runs ONE exec `mkdir -p` probe
+* whose stdout discloses created-vs-existed. Best-effort by contract: any
+* failure records created:'n-a' + note and lets the copy proceed so the native
+* CLI surfaces the real error (and stopped-container docker cp keeps working). */
+async function ensureDestinationDir(dst, signal, execArgvFor, wrap, receipt) {
+	const dir = dirname(dst.path);
+	if (dir === "/" || dir === ".") {
+		receipt.created = false;
+		return;
+	}
+	if (dst.plan.kind === "local") {
+		try {
+			if (existsSync(dir)) {
+				receipt.created = false;
+				return;
+			}
+			mkdirSync(dir, { recursive: true });
+			receipt.created = true;
+		} catch (error) {
+			receipt.created = "n-a";
+			receipt.note = `mkdir pre-hop failed: ${error instanceof Error ? error.message : String(error)}`;
+		}
+		return;
+	}
+	if (execArgvFor === void 0) {
+		receipt.created = "n-a";
+		return;
+	}
+	if (/[\r\n]/.test(dir)) {
+		receipt.created = "n-a";
+		receipt.note = "mkdir pre-hop skipped: newline-bearing destination path";
+		return;
+	}
+	const quoted = `'${dir.replaceAll("'", "'\\\\''")}'`;
+	const script = `if [ -d ${quoted} ]; then echo existed; else mkdir -p ${quoted} && echo created; fi`;
+	try {
+		const result = await runNative(wrap(execArgvFor(dst.plan, script)), signal);
+		const word = result.stdout.trim().split("\n").pop();
+		if (result.exit === 0 && word === "created") receipt.created = true;
+		else if (result.exit === 0 && word === "existed") receipt.created = false;
+		else {
+			receipt.created = "n-a";
+			const tail = result.stderr.trim().split("\n").filter((line) => line.length > 0).pop();
+			receipt.note = `mkdir pre-hop unavailable (exit ${result.exit})${tail !== void 0 ? `: ${tail}` : ""}`;
+		}
+	} catch (error) {
+		receipt.created = "n-a";
+		receipt.note = `mkdir pre-hop failed: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
 /** 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)`);
+/** D8 (2026-10-14 user adoption, third acceptance round): a LOCAL directory source gets
+*  the route's recursive flag appended automatically — scp / incus file push refuse
+*  directories without it. The appended flag lands in the executed argv, which the
+*  receipt shows verbatim: disclosure by receipt, never silent. Remote sources stay
+*  caller-explicit (we do not dial just to stat); an explicit caller flag wins. */
+async function recursiveFlag(localPath, callerArgv, flag) {
+	if (callerArgv.includes(flag) || callerArgv.includes("--recursive")) return [];
+	try {
+		if ((await stat(localPath)).isDirectory()) return [flag];
+	} catch {}
+	return [];
+}
+/** docker cp follows symlinks only with -L; its native error ("invalid symlink")
+*  names no remedy. Append the one-line hint on that failure path (F5, 2026-10-14). */
+function withSymlinkHint(result) {
+	if (result.exit !== 0 && /invalid symlink/i.test(result.stderr)) result.stderr = `${result.stderr}\nhint: docker cp follows symlinks only with -L — pass argv:["-L"] (e.g. /etc/os-release is a symlink)`;
+}
+async function tempSshConfig(source, destination, runNative$1) {
+	const resolvedSource = await resolveThroughOriginConfig(source, runNative$1);
+	const resolvedDestination = await resolveThroughOriginConfig(destination, runNative$1);
+	for (const { connection: c, identityFiles } of [resolvedSource, resolvedDestination]) {
+		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)`);
+		for (const idFile of identityFiles) if (/[\r\n]/.test(idFile)) throw new Error("remote: scp -3 temp config rejects newline in resolved IdentityFile (no config injection)");
+	}
 	const dir = await mkdtemp(join(tmpdir(), "superd-scp3-"));
 	const path$1 = join(dir, "config");
-	const block = (name$1, c) => {
+	const block = (name$1, c, identityFiles) => {
 		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}`);
+		for (const idFile of [c.key !== void 0 ? [c.key] : [], identityFiles].flat()) lines.push(`  IdentityFile ${idFile}`);
 		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 writeFile(path$1, `${block("superd-scp3-source", resolvedSource.connection, resolvedSource.identityFiles)}\n${block("superd-scp3-destination", resolvedDestination.connection, resolvedDestination.identityFiles)}\n`, { mode: 384 });
 	await chmod(path$1, 384);
 	return {
 		path: path$1,
 		dir
 	};
 }
+/** Effective fields for one connection per the origin's own ssh config (ssh -G,
+*  prints resolved settings without dialing). Explicit fields win; empty/none
+*  proxyjump is dropped. IdentityFile PATHS from the config are returned separately
+*  for inlining into the temp config — a path is not key material and stays on the
+*  origin (F1, 2026-10-14: dev4's only authorized key lived in config, not the agent;
+*  dropping it made scp -3 fail with a bare Permission denied). */
+async function resolveThroughOriginConfig(c, runNative$1) {
+	let probe;
+	try {
+		probe = await runNative$1([
+			"ssh",
+			"-G",
+			c.host
+		], new AbortController().signal);
+	} catch {
+		probe = void 0;
+	}
+	if (probe === void 0 || probe.exit !== 0) return {
+		connection: c,
+		identityFiles: []
+	};
+	const lines = probe.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	const pick = (key) => lines.find((line) => line.startsWith(`${key} `))?.slice(key.length + 1).trim() || void 0;
+	const home = process.env.HOME ?? "";
+	const compiledDefault = (path$1) => path$1 === "none" || [
+		"id_rsa",
+		"id_ecdsa",
+		"id_ecdsa_sk",
+		"id_ed25519",
+		"id_ed25519_sk"
+	].some((name$1) => path$1 === `~/.ssh/${name$1}` || home !== "" && path$1 === `${home}/.ssh/${name$1}`);
+	const identityFiles = [...new Set(lines.filter((line) => line.startsWith("identityfile ")).map((line) => line.slice(13).trim()).filter((path$1) => path$1 !== "" && !compiledDefault(path$1)))];
+	const host = (pick("hostname") ?? c.host).replace(/^.*@/, "");
+	const user = c.user ?? pick("user");
+	const portText = pick("port");
+	const port = c.port ?? (portText !== void 0 && /^\d+$/.test(portText) ? Number(portText) : void 0);
+	const proxyJumpRaw = c.proxyJump ?? pick("proxyjump");
+	return {
+		connection: {
+			host,
+			...user !== void 0 && user !== "" ? { user } : {},
+			...port !== void 0 && Number.isInteger(port) && port > 0 ? { port } : {},
+			...c.key !== void 0 ? { key: c.key } : {},
+			...proxyJumpRaw !== void 0 && proxyJumpRaw !== "" && proxyJumpRaw.toLowerCase() !== "none" ? { proxyJump: proxyJumpRaw } : {}
+		},
+		identityFiles
+	};
+}
 
 //#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. */
+* remote command; forwarding options go before `--`, the host after it.
+* Identity core comes from ssh-argv.ts (the ONE policy — 2026-10-17 ruling). */
 function relaySsh(connection, extra, command) {
-	const args = [
-		"ssh",
+	return sshCommandArgv(connection, [
 		"-o",
 		"BatchMode=yes",
 		"-T",
@@ -961,14 +1156,7 @@ function relaySsh(connection, extra, command) {
 		"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;
+	], extra, command);
 }
 async function freePorts(count) {
 	const servers = [];
@@ -1123,12 +1311,16 @@ async function forwardRoute(argv, source, destination, signal, options) {
 		return await removeRemoteTemp(destination.connection, temp, wrap) ? "released" : "unknown";
 	};
 	try {
+		signal.throwIfAborted();
+		const daemonState = await waitForDaemonReady(destinationChild, 5e3);
+		if (daemonState === "exited") throw new Error(`dual-SSH rsync destination daemon exited before serving${relayDetail(destinationChild, sourceHold)}`);
+		if (daemonState === "timeout") throw new Error(`dual-SSH rsync destination daemon never announced readiness${relayDetail(destinationChild, sourceHold)}`);
 		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) 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,
@@ -1153,6 +1345,19 @@ async function forwardRoute(argv, source, destination, signal, options) {
 		await Promise.allSettled([destinationChild.stop(), sourceHold.stop()]);
 	}
 }
+/** Wait until the destination daemon script announces itself (stderr marker,
+*  printed after its directory check and right before the daemon exec) or exits.
+*  'ready' only when the daemon is actually about to serve — closes the 0.3.1-e
+*  race where -L opens at session start but the script dies ~150ms later. */
+async function waitForDaemonReady(held, budgetMs) {
+	const deadline = Date.now() + budgetMs;
+	for (;;) {
+		if (/^SUPERD-RSYNC-TMP \S+$/m.test(held.stderrSink.text)) return "ready";
+		if (held.child.exitCode !== null) return "exited";
+		if (Date.now() >= deadline) return "timeout";
+		await new Promise((resolve$1) => setTimeout(resolve$1, 50));
+	}
+}
 function relayDetail(...held) {
 	const detail = held.map((child) => child.stderrSink.text).filter(Boolean).join("\n");
 	return detail ? `\n[relay stderr]\n${detail}` : "";
@@ -1234,14 +1439,7 @@ async function runRsync(request, source, destination, signal, options = {}) {
 	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)`);
+	for (const key of Object.keys(request)) if (key !== "src" && key !== "dst" && key !== "argv") throw new Error(`remote: rsync rejects unknown field "${key}" — native options go through argv (verify is a copy Hub-lane option; mkdir is copy-only; for destination parents pass --mkpath yourself)`);
 	if (!source.connection && !destination.connection) throw new Error("rsync requires at least one SSH endpoint; local-only is unsupported");
 	let result;
 	let route;
@@ -1289,6 +1487,9 @@ async function runRsync(request, source, destination, signal, options = {}) {
 		dst: request.dst,
 		argv,
 		route,
+		verification: "native-exit-only",
+		ok: result.exit === 0,
+		...result.exit === 0 ? {} : { reason: signal.aborted ? "aborted" : "non-zero-exit" },
 		command: `rsync ${argv.join(" ")}`,
 		...itemized.length > 0 || argv.includes("--itemize-changes") || argv.includes("-i") ? { itemizedChanges: itemized } : {},
 		...literalBytes === void 0 ? {} : { literalBytes },
@@ -1303,21 +1504,14 @@ async function runRsync(request, source, destination, signal, options = {}) {
 * 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(" ")} "$@"`,
+		`shift; exec ${wrap(sshCommandArgv(connection, [
+			"-o",
+			"BatchMode=yes",
+			"-T"
+		], [])).map(rshQuote).join(" ")} "$@"`,
 		"rsync-rsh"
 	].map(rshQuote).join(" ");
 }
@@ -1413,26 +1607,19 @@ var SshTargets = class {
 	}
 };
 /** Shared by execution, probes and file/relay consumers. extraArgs is trusted
-* internal SSH argv (e.g. forwarding), never a model-provided shell string. */
+* internal SSH argv (e.g. forwarding), never a model-provided shell string.
+* Identity assembly lives in ssh-argv.ts (the ONE policy — 2026-10-17 ruling);
+* this wrapper only picks the tty/batch dialect base. */
 function sshArgv(connection, options = {}) {
-	const args = options.tty ? [
-		"ssh",
+	return sshCommandArgv(connection, options.tty ? [
 		"-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;
+	], options.extraArgs ?? [], options.command);
 }
 
 //#endregion
@@ -1489,6 +1676,96 @@ async function runOneShot(argv, opts = {}) {
 	};
 }
 
+//#endregion
+//#region src/remote/helper.ts
+/** Reads helper-bin/MANIFEST.json next to the compiled module (lib/remote in the npm
+* package, super-dsh/remote in the Super closure — same relative layout). Missing or
+* malformed assets ⇒ null ⇒ shim-only mode; never throws. */
+function helperAssets(baseDir) {
+	const dir = baseDir ?? join(dirname(fileURLToPath(import.meta.url)), "helper-bin");
+	try {
+		const manifest = JSON.parse(readFileSync(join(dir, "MANIFEST.json"), "utf8"));
+		if (manifest?.format !== 1 || typeof manifest.ver !== "string" || typeof manifest.protocol !== "number" || !manifest.targets || typeof manifest.targets !== "object") return null;
+		return {
+			dir,
+			manifest
+		};
+	} catch {
+		return null;
+	}
+}
+/** `uname -s`/`uname -m` → shipped target triple. Unknown combos ⇒ null (shim). */
+function archTriple(sys, machine, shipped) {
+	const s = sys.trim().toLowerCase(), m = machine.trim().toLowerCase();
+	const candidates = s === "linux" ? m === "x86_64" || m === "amd64" ? "x86_64-unknown-linux-musl" : m === "aarch64" || m === "arm64" ? "aarch64-unknown-linux-musl" : null : s === "darwin" ? m === "arm64" || m === "aarch64" ? "aarch64-apple-darwin" : null : null;
+	if (candidates === null) return null;
+	return shipped.has(candidates) ? candidates : null;
+}
+function planKey(plan) {
+	switch (plan.kind) {
+		case "ssh": {
+			const c = plan.connection;
+			const host = c?.host ?? plan.host;
+			return `ssh|${c?.user ? c.user + "@" : ""}${host}${c?.port ? ":" + c.port : ""}${c?.proxyJump ? "|" + c.proxyJump : ""}`;
+		}
+		case "docker": return `docker|${plan.container}`;
+		case "incus": return `incus|${plan.container}`;
+	}
+}
+const PROBE_RE = /^SUPERD-PROBE (\S+) (\S+)$/m;
+const READY_RE = /^SUPERD-READY (\S+)$/m;
+var HelperRegistry = class {
+	states = /* @__PURE__ */ new Map();
+	constructor(assets, exec, probeArgv, uploadArgv) {
+		this.assets = assets;
+		this.exec = exec;
+		this.probeArgv = probeArgv;
+		this.uploadArgv = uploadArgv;
+	}
+	/** Never throws: any bootstrap failure resolves null (sticky) and the caller stays on the shim. */
+	ensure(plan) {
+		if (plan.kind !== "ssh" && plan.kind !== "docker" && plan.kind !== "incus") return Promise.resolve(null);
+		const key = planKey(plan);
+		let entry = this.states.get(key);
+		if (entry === void 0) {
+			entry = this.bootstrap(plan).catch(() => null);
+			entry.catch(() => {});
+			this.states.set(key, entry);
+		}
+		return entry;
+	}
+	async bootstrap(plan) {
+		const { manifest } = this.assets;
+		const first = await this.exec(this.probeArgv(plan, this.assets), { timeoutSec: 15 });
+		const ready = this.parseReady(first.stdout, manifest.ver, manifest.protocol);
+		if (ready !== null) return ready;
+		const probe = PROBE_RE.exec(first.stdout);
+		if (probe === null || first.exit !== 90 && first.exit !== 0) return null;
+		const triple = archTriple(probe[1], probe[2], new Set(Object.keys(manifest.targets)));
+		if (triple === null) return null;
+		const target = manifest.targets[triple];
+		const binary = await readFile(join(this.assets.dir, triple, target.file));
+		if ((await this.exec(this.uploadArgv(plan, triple, target.file, this.assets), {
+			stdin: binary,
+			timeoutSec: 60
+		})).exit !== 0) return null;
+		const second = await this.exec(this.probeArgv(plan, this.assets), { timeoutSec: 15 });
+		return this.parseReady(second.stdout, manifest.ver, manifest.protocol);
+	}
+	parseReady(stdout, ver, protocol) {
+		const ready = READY_RE.exec(stdout);
+		const banner = /^SUPERD-RUN proto=(\d+) name=superd-run ver=(\S+) target=(\S+)/m.exec(stdout);
+		if (ready === null || banner === null) return null;
+		if (banner[1] !== String(protocol) || banner[2] !== ver) return null;
+		return {
+			binPath: ready[1],
+			triple: banner[3],
+			ver,
+			protocol
+		};
+	}
+};
+
 //#endregion
 //#region src/remote/transports.ts
 /** POSIX 单引号机械转义（唯一一层转义，spec §三"一层机械转义"）。 */
@@ -1568,6 +1845,104 @@ function buildSpawnArgv(spawnCommand) {
 		"/dev/null"
 	];
 }
+/** superd-run helper argv (spec: docs/specs/remote-rescope §5). Probe and upload are single
+*  `sh -c` hops (busybox/alpine/darwin-safe); run/killgroup over ssh go through exactly one
+*  remote-shell parse, same discipline as buildOneShotArgv. */
+function buildHelperProbeArgv(plan, assets) {
+	const { ver, targets } = assets.manifest;
+	return helperShellArgv(plan, `${Object.entries(targets).map(([triple, t]) => `d="$HOME/.cache/superd/run/${triple}-${ver}"; [ -x "$d/${t.file}" ] && { echo "SUPERD-READY $d/${t.file}"; "$d/${t.file}" banner; exit 0; };`).join(" ")} echo "SUPERD-PROBE $(uname -s 2>/dev/null || echo unknown) $(uname -m 2>/dev/null || echo unknown)"; exit 90`);
+}
+function buildHelperUploadArgv(plan, triple, file, assets) {
+	const dir = `$HOME/.cache/superd/run/${triple}-${assets.manifest.ver}`;
+	return helperShellArgv(plan, `mkdir -p "${dir}" && cat > "${dir}/${file}.tmp" && chmod 0755 "${dir}/${file}.tmp" && mv -f "${dir}/${file}.tmp" "${dir}/${file}"`);
+}
+function buildHelperOneShotArgv(plan, binPath, options) {
+	const { tag, cmd } = options;
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `exec ${shQuote(binPath)} run --tag ${shQuote(tag)} -- bash -lc ${shQuote(cmd)}` });
+		case "docker": return [
+			"docker",
+			"exec",
+			"-i",
+			"--",
+			plan.container,
+			binPath,
+			"run",
+			"--tag",
+			tag,
+			"--",
+			"bash",
+			"-lc",
+			cmd
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			binPath,
+			"run",
+			"--tag",
+			tag,
+			"--",
+			"bash",
+			"-lc",
+			cmd
+		];
+	}
+}
+function buildHelperKillgroupArgv(plan, binPath, tag) {
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `${shQuote(binPath)} killgroup --tag ${shQuote(tag)}` });
+		case "docker": return [
+			"docker",
+			"exec",
+			"--",
+			plan.container,
+			binPath,
+			"killgroup",
+			"--tag",
+			tag
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			binPath,
+			"killgroup",
+			"--tag",
+			tag
+		];
+	}
+}
+function helperShellArgv(plan, script) {
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: script });
+		case "docker": return [
+			"docker",
+			"exec",
+			"-i",
+			"--",
+			plan.container,
+			"sh",
+			"-c",
+			script
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			"sh",
+			"-c",
+			script
+		];
+	}
+}
 
 //#endregion
 //#region src/remote/nonce-framing.ts
@@ -2297,6 +2672,9 @@ var RemoteDriver = class {
 	starting = /* @__PURE__ */ new Set();
 	fileAbort = new AbortController();
 	disposed = false;
+	/** undefined = 未尝试；null = 资产缺失（shim-only）；registry = 每 target sticky 状态机。 */
+	helpers;
+	runnerOf = /* @__PURE__ */ new WeakMap();
 	disposal;
 	constructor(opts = {}) {
 		this.opts = opts;
@@ -2403,13 +2781,18 @@ var RemoteDriver = class {
 				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)");
+			if (request.verify !== void 0) throw new Error("copy: verify is a Hub/local staged lane option (independent SHA-256); native routes report exit-code-only verification — self-verify via oneshot digest commands when needed");
 			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");
+			const execArgvFor = (plan, script) => {
+				const argv = helperShellArgv(plan, script);
+				return this.opts.nativeArgvFor ? this.opts.nativeArgvFor(argv) : argv;
+			};
 			return nativeCopy({
 				src: request.src,
 				dst: request.dst,
+				...request.mkdir === void 0 ? {} : { mkdir: request.mkdir },
 				...request.argv === void 0 ? {} : { argv: request.argv },
 				...request.pullArgv === void 0 ? {} : { pullArgv: request.pullArgv },
 				...request.pushArgv === void 0 ? {} : { pushArgv: request.pushArgv }
@@ -2422,7 +2805,10 @@ var RemoteDriver = class {
 					plan: dstPlan,
 					path: dst.path
 				}
-			}, combined, { wrapArgv: this.opts.nativeArgvFor });
+			}, combined, {
+				wrapArgv: this.opts.nativeArgvFor,
+				execArgvFor
+			});
 		})();
 		this.starting.add(work);
 		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
@@ -2489,12 +2875,32 @@ var RemoteDriver = class {
 		if (signal.aborted || this.disposed) process$1.cancel("owner closed during start");
 		return process$1;
 	}
-	nativeProcess(plan, params, timeoutSec, signal = this.fileAbort.signal) {
+	async nativeProcess(plan, params, timeoutSec, signal = this.fileAbort.signal) {
 		const cleanupTag = randomUUID().slice(0, 8);
+		const helper = await this.ensureHelper(plan);
+		if (helper !== null && !this.disposed) {
+			const process$2 = startOneShot(buildHelperOneShotArgv(plan, helper.binPath, {
+				tag: cleanupTag,
+				cmd: params.cmd
+			}), {
+				stdin: params.stdin,
+				timeoutSec
+			});
+			this.runnerOf.set(process$2, `superd-run ${helper.ver} (${helper.triple})`);
+			process$2.done.then((result) => {
+				if (!result.cancelled && !result.timedOut) return;
+				startOneShot(buildHelperKillgroupArgv(plan, helper.binPath, cleanupTag), { timeoutSec: 15 }).done.catch(() => {});
+			}).catch(() => {});
+			const tracked = Promise.resolve(process$2);
+			this.starting.add(tracked);
+			tracked.then(() => this.starting.delete(tracked), () => this.starting.delete(tracked));
+			return tracked;
+		}
 		const process$1 = startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, params.cmd, { cleanupTag }), {
 			stdin: params.stdin,
 			timeoutSec
 		});
+		this.runnerOf.set(process$1, "posix-shim");
 		process$1.done.then((result) => {
 			if (!result.cancelled && !result.timedOut) return;
 			const pidfile = `"\${TMPDIR:-/tmp}/superd-oneshot-${cleanupTag}.pgid"`;
@@ -2506,6 +2912,38 @@ var RemoteDriver = class {
 		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
 		return work;
 	}
+	/** Helper bootstrap is best-effort and sticky: any failure parks null for this driver
+	*  lifetime and the shim stays the path. First call to a target pays probe (+ upload). */
+	async ensureHelper(plan) {
+		if (this.helpers === void 0) {
+			const assets = this.opts.helperAssetsFor?.() ?? helperAssets();
+			this.helpers = assets === null ? null : new HelperRegistry(assets, (argv, options) => this.helperExec(argv, options), buildHelperProbeArgv, buildHelperUploadArgv);
+		}
+		if (this.helpers === null || this.disposed) return null;
+		try {
+			return await this.helpers.ensure(plan);
+		} catch {
+			return null;
+		}
+	}
+	async helperExec(argv, options) {
+		this.assertOpen();
+		const stdin = options?.stdin;
+		if (stdin !== void 0) {
+			const proc$1 = startBinaryProcess(argv, { timeoutSec: options?.timeoutSec });
+			proc$1.stdin.on("error", () => {});
+			proc$1.stdin.end(stdin);
+			return {
+				exit: (await proc$1.done).exit,
+				stdout: ""
+			};
+		}
+		const proc = startOneShot(argv, { timeoutSec: options?.timeoutSec });
+		return {
+			exit: (await proc.done).exit,
+			stdout: proc.read("stdout", 0).text
+		};
+	}
 	own(process$1) {
 		this.processes.add(process$1);
 		process$1.done.then(() => this.processes.delete(process$1));
@@ -2783,7 +3221,8 @@ var RemoteDriver = class {
 					stderr: err?.stats ?? r$1.outputStats?.stderr
 				} } : {},
 				durationMs: r$1.durationMs,
-				...out$1.truncated !== void 0 ? { truncated: out$1.truncated } : {}
+				...out$1.truncated !== void 0 ? { truncated: out$1.truncated } : {},
+				...this.runnerOf.get(process$1) === void 0 ? {} : { runner: this.runnerOf.get(process$1) }
 			};
 		}
 		const argv = (this.opts.ptyArgvFor ?? buildPtyArgv)(routing.plan);
@@ -2946,9 +3385,9 @@ const REMOTE_TOOL_DESCRIPTION = `Remote execution and file transfer over ssh / d
   {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.
+oneshot: stateless bash -lc, stdout/stderr separate, exit code verbatim. Supervision prefers a pinned superd-run helper cached on the endpoint (~/.cache/superd/run; first call uploads it over the same exec lane) and falls back to a POSIX wrapper everywhere else — the result field "runner" says which ran. Helper or wrapper, backgrounded children are reaped on completion and the whole group is killed on timeout/cancel; the endpoint needs bash only (no Python).
 
-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.
+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 (uppercase — scp's remote-client mode) is refused; copy of a directory from a LOCAL source auto-appends the route's recursive flag (-r, shown in the receipt argv); from a REMOTE source pass -r yourself or use rsync; mkdir defaults to ensuring the destination's PARENT directory first (one exec pre-hop, outcome in the receipt created field; the operand itself is never pre-created); receipts use stable route ids (scp / scp-3 / docker-cp / incus-file-push / incus-file-pull / staged-pull-push / hub-staged) with ok+reason, the verification tier actually performed (native-exit-only by default; sha256 on the Hub lane) and tool-owned temp paths in argv shown as placeholders. 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 = {}) {
@@ -2973,7 +3412,7 @@ function createRemoteTool(driver, opts = {}) {
 			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."
+				description: "Ordered native CLI options and values for one-command routes (e.g. rsync [\"-a\",\"--partial\",\"--dry-run\"], scp [\"-p\",\"-r\"], 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. docker cp: pass -L to follow symlinks (a symlink source like /etc/os-release fails without it). Two-segment cross-endpoint copy uses pullArgv/pushArgv instead."
 			},
 			pullArgv: {
 				type: "array",
@@ -2987,11 +3426,11 @@ function createRemoteTool(driver, opts = {}) {
 			},
 			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."
+				description: "copy only. Receipts name the verification tier actually performed (D1=A): native CLI routes are \"native-exit-only\" (no independent check — self-verify via oneshot digest commands when needed); the Hub↔local staged lane computes independent SHA-256 digests by default and verify:false skips them (\"not-applicable\"). No hash tier exists on native routes."
 			},
 			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."
+				description: "copy only, all routes. Default true: before transfer, one best-effort exec pre-hop ensures the destination's PARENT directory exists (the operand itself is never pre-created — each CLI's own layout semantics stay byte-identical). Receipt created field: true (parent created this call) / false (already existed) / \"n-a\" (skipped or pre-hop unavailable, e.g. docker exec on a stopped container — the native CLI then reports the real error itself). false skips the pre-hop."
 			},
 			run_in_background: {
 				type: "boolean",
@@ -3088,7 +3527,11 @@ function createRemoteTool(driver, opts = {}) {
 					outputStats: { type: "json" },
 					outputStatsUnavailable: { type: "boolean" },
 					session: { type: "string" },
-					notice: { type: "string" }
+					notice: { type: "string" },
+					runner: {
+						type: "string",
+						description: "oneshot supervision path: superd-run <ver> (<triple>) or posix-shim"
+					}
 				}
 			},
 			render: (_args, value) => [{
@@ -3110,12 +3553,26 @@ function createRemoteTool(driver, opts = {}) {
 					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\""})`);
+				const KNOWN_PARAMS = new Set([
+					"action",
+					"src",
+					"dst",
+					"argv",
+					"pullArgv",
+					"pushArgv",
+					"verify",
+					"mkdir",
+					"run_in_background",
+					"target",
+					"ssh",
+					"spawn",
+					"cmd",
+					"script",
+					"mode",
+					"stdin",
+					"timeout"
+				]);
+				for (const key of Object.keys(args)) if (!KNOWN_PARAMS.has(key)) throw new Error(`remote: unknown parameter "${key}" — this surface has no legacy aliases (dryRun/delete/excludes/preserve are gone); pass native CLI options through argv instead`);
 				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");
@@ -3125,15 +3582,17 @@ function createRemoteTool(driver, opts = {}) {
 						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));
+					if (receipt$1.ok === false || receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
+					const rsyncDuration = Date.now() - start;
 					return {
 						kind: "rsync",
-						text: JSON.stringify(receipt$1),
+						text: formatTransferLine("rsync", receipt$1, rsyncDuration),
 						receipt: receipt$1,
 						exit: receipt$1.exit,
-						durationMs: Date.now() - start
+						durationMs: rsyncDuration
 					};
 				}
+				const copyStart = Date.now();
 				const receipt = await driver.copy({
 					src: args.src,
 					dst: args.dst,
@@ -3143,12 +3602,16 @@ function createRemoteTool(driver, opts = {}) {
 					...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
 					...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
 				}, exec.signal, { sessionKey: getSessionKey(exec) });
+				const asReceipt = receipt;
+				const exits = asReceipt.exits ?? [];
+				if (asReceipt.ok === false || exits.some((code) => code !== 0)) throw new Error(JSON.stringify(receipt));
+				const copyDuration = Date.now() - copyStart;
 				return {
 					kind: "copy",
-					text: JSON.stringify(receipt),
+					text: formatTransferLine("copy", receipt, copyDuration),
 					receipt,
-					exit: null,
-					durationMs: 0
+					exit: exits.length > 0 ? 0 : null,
+					durationMs: copyDuration
 				};
 			}
 			if ([
@@ -3234,6 +3697,7 @@ function createRemoteTool(driver, opts = {}) {
 			if (r.outputStatsUnavailable) v.outputStatsUnavailable = true;
 			if (r.session !== void 0) v.session = r.session;
 			if (r.notice !== void 0) v.notice = r.notice;
+			if (r.runner !== void 0) v.runner = r.runner;
 			return v;
 		}
 	});
@@ -3244,6 +3708,26 @@ function createRemoteTool(driver, opts = {}) {
 	});
 	return tool;
 }
+/** S8 (2026-10-17): copy/rsync render as one formatted line; the full receipt
+* stays in the receipt field — raw-JSON dumps are gone from text. */
+function formatTransferLine(action, receipt, durationMs) {
+	const r = receipt;
+	const parts = [];
+	if (r.ok === false) parts.push(`✗ ${r.reason ?? "failed"}`);
+	parts.push(`${action} ${r.src} → ${r.dst}`);
+	if (r.route !== void 0 && r.route !== "") parts.push(`route ${r.route}`);
+	if (r.exits !== void 0) parts.push(`exits [${r.exits.join(",")}]`);
+	else if (r.exit !== void 0) parts.push(`exit ${r.exit}`);
+	if (r.verification !== void 0) parts.push(`verification ${r.verification}`);
+	if (r.created === true) parts.push("created yes");
+	else if (r.created === false) parts.push("created pre-existing");
+	else if (r.created === "n-a") parts.push("created n-a");
+	if (r.cleanup !== void 0 && r.cleanup !== "none-required") parts.push(`cleanup ${r.cleanup}`);
+	if (typeof r.bytes === "number") parts.push(`${r.bytes} bytes / ${r.entries} entries`);
+	parts.push(`${(durationMs / 1e3).toFixed(1)}s`);
+	if (r.note !== void 0 && r.note.length > 0) parts.push(`(${r.note})`);
+	return parts.join(" · ");
+}
 function renderValue(v) {
 	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "copy" || v.kind === "rsync") return v.text;
 	const parts = [];
@@ -3258,7 +3742,8 @@ function renderValue(v) {
 	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}` : "";
-	parts.push(`[exit ${v.exit} · ${secs}s${suffix}${cwdTag}${sessionTag}]`);
+	const runnerTag = typeof v.runner === "string" && v.runner.length > 0 ? ` · runner ${v.runner}` : "";
+	parts.push(`[exit ${v.exit} · ${secs}s${suffix}${cwdTag}${sessionTag}${runnerTag}]`);
 	if (v.stderr !== void 0 && v.stderr.length > 0) parts.push("[stderr]", v.stderr);
 	return parts.join("\n");
 }