super-dsh 0.3.1-a → 0.3.1-b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-dsh",
-  "version": "0.3.1-a",
+  "version": "0.3.1-b",
   "description": "Super D for the DeepSeek Harness (DSH) — one dsh plugin that mounts the superd hub (runtime selector, roster, per-runtime agents) and joins local foreign-agent runtimes (OMP, Codex, Claude, Pi, Hermes, Antigravity) into the DSH Web UI. Each runtime keeps its native home and session store; the hub only bridges.",
   "type": "module",
   "license": "MIT",

package/remote/helper-bin/MANIFEST.json

@@ -0,0 +1,35 @@
+{
+  "format": 1,
+  "name": "superd-run",
+  "ver": "0.3.1-b",
+  "protocol": 1,
+  "targets": {
+    "aarch64-apple-darwin": {
+      "file": "superd-run",
+      "bytes": 337808,
+      "sha256": "715c2d7bd935f3b4cc4ae0ffb10d3fab946bb62d93f592ccfe2a7446669ff76b"
+    },
+    "aarch64-unknown-linux-musl": {
+      "file": "superd-run",
+      "bytes": 397416,
+      "sha256": "22ac1c7f913092d8ca8d312b93528dd2263200f9670dc183fd215bc89d2bac68"
+    },
+    "x86_64-pc-windows-gnu": {
+      "file": "superd-run.exe",
+      "bytes": 336896,
+      "sha256": "a638479e1ccb1c4e185085100450962e39164158a76097b5087d2a3bb8880ac0"
+    },
+    "x86_64-unknown-linux-musl": {
+      "file": "superd-run",
+      "bytes": 447152,
+      "sha256": "79e42879509bb87d2fe9888d282151fd17113203d3172f59a16fcb5a180ba057"
+    }
+  },
+  "sources": {
+    "Cargo.toml": "129ab8360e9da872f9dfd6e713d81fe1389735a74d781f3d9c15e110f92d2757",
+    "build.rs": "c4fb356956b1ec700e99bdeca07d657a7d3b2a4026582db136411676da3d125e",
+    "src/main.rs": "47f1648ea1abc30583839edab219a9062c83d57be981c0505ab6bf79c6fbff54",
+    "src/unix.rs": "56c5f523b7b1a9efd50ef24ccdabc024bc065dd2f904fdbecdf0ca49fe7f3393",
+    "src/windows.rs": "6c1537424b1adc05ed17c7cf8bf376fb5711602b9da1697d596155bf21d541da"
+  }
+}

package/remote/helper-bin/aarch64-apple-darwin/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-b

package/remote/helper-bin/aarch64-unknown-linux-musl/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-b

package/remote/helper-bin/x86_64-pc-windows-gnu/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-b

package/remote/helper-bin/x86_64-unknown-linux-musl/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-b

package/remote/plugin.d.ts

@@ -213,6 +213,23 @@ interface RsyncReceipt extends RunResult {
  */
 declare function runRsync(request: RsyncRequest, source: RsyncEndpoint, destination: RsyncEndpoint, signal: AbortSignal, options?: RelayRsyncOptions): Promise<RsyncReceipt>;
 //#endregion
+//#region src/remote/helper.d.ts
+interface HelperManifest {
+  format: 1;
+  name: string;
+  ver: string;
+  protocol: number;
+  targets: Record<string, {
+    file: string;
+    bytes: number;
+    sha256: string;
+  }>;
+}
+interface HelperAssets {
+  dir: string;
+  manifest: HelperManifest;
+}
+//#endregion
 //#region src/remote/process.d.ts
 declare const PROCESS_CLEANUP_BOUND_MS: number;
 interface ProcessOptions {
@@ -287,6 +304,8 @@ interface RemoteCallResult {
   session?: string;
   /** 引导/教学行（同 label 重复给 spawn 时的「可省略 spawn」提示等）；无则省略。 */
   notice?: string;
+  /** oneshot 监督路径的如实标注：`superd-run <ver> (<triple>)` 或 `posix-shim`（spec remote-rescope §5）。 */
+  runner?: string;
 }
 interface RemoteAuditRecord {
   target: string;
@@ -311,6 +330,8 @@ interface RemoteDriverOptions {
   ptyArgvFor?: (plan: TargetPlan) => string[];
   spawnArgvFor?: (spawnCommand: string) => string[];
   probeRunner?: ProbeOptions['runner'];
+  /** 测试/验收缝：helper 资产来源（默认 lib 旁挂 helper-bin）；显式 null 强制 shim 路径。 */
+  helperAssetsFor?: () => HelperAssets | null;
   /** 测试缝：roster 扫描执行器（bare-name 解析复用）。 */
   rosterRunner?: RosterOptions['runner'];
   /** 测试缝：ssh config 读取（bare-name 解析复用）。 */
@@ -327,6 +348,9 @@ declare class RemoteDriver {
   private readonly starting;
   private readonly fileAbort;
   private disposed;
+  /** undefined = 未尝试；null = 资产缺失（shim-only）；registry = 每 target sticky 状态机。 */
+  private helpers;
+  private readonly runnerOf;
   private disposal;
   constructor(opts?: RemoteDriverOptions);
   call(params: RemoteCallParams, callCtx?: {
@@ -350,6 +374,10 @@ declare class RemoteDriver {
   start(input: RemoteInput, signal: AbortSignal): Promise<RemoteProcess>;
   private startPrepared;
   private nativeProcess;
+  /** 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). */
+  private ensureHelper;
+  private helperExec;
   private own;
   /** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
   /**

package/remote/plugin.js

@@ -1,6 +1,6 @@
 import { Context } from "@deepseek-ai/cordis";
-import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
-import { constants, createReadStream, createWriteStream, mkdirSync, statSync } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { constants, createReadStream, createWriteStream, mkdirSync, readFileSync, statSync } from "node:fs";
 import { pipeline } from "node:stream/promises";
 import { dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { Readable } from "node:stream";
@@ -8,6 +8,7 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { spawn } from "node:child_process";
 import { createConnection, createServer } from "node:net";
+import { fileURLToPath } from "node:url";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 
 //#region third_party/schemastery/node_modules/@deepseek-ai/cosmokit/lib/index.js
@@ -1631,6 +1632,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 		const argv = [
 			"scp",
 			...identityArgv(connection),
+			...await recursiveFlag(endpoints.src.path, oneShot, "-r"),
 			...oneShot,
 			endpoints.src.path,
 			scpSpec(connection, endpoints.dst.path)
@@ -1663,7 +1665,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}`;
@@ -1695,7 +1697,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 = [
@@ -1705,13 +1709,16 @@ 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}`
@@ -1805,30 +1812,100 @@ function segmentArgv(plan, remote, staged, opts, leg) {
 }
 /** 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 = 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, `${block("superd-scp3-source", source)}\n${block("superd-scp3-destination", destination)}\n`, { mode: 384 });
+	await writeFile(path, `${block("superd-scp3-source", resolvedSource.connection, resolvedSource.identityFiles)}\n${block("superd-scp3-destination", resolvedDestination.connection, resolvedDestination.identityFiles)}\n`, { mode: 384 });
 	await chmod(path, 384);
 	return {
 		path,
 		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$1 = (key) => lines.find((line) => line.startsWith(`${key} `))?.slice(key.length + 1).trim() || void 0;
+	const home = process.env.HOME ?? "";
+	const compiledDefault = (path) => path === "none" || [
+		"id_rsa",
+		"id_ecdsa",
+		"id_ecdsa_sk",
+		"id_ed25519",
+		"id_ed25519_sk"
+	].some((name$1) => path === `~/.ssh/${name$1}` || home !== "" && path === `${home}/.ssh/${name$1}`);
+	const identityFiles = [...new Set(lines.filter((line) => line.startsWith("identityfile ")).map((line) => line.slice(13).trim()).filter((path) => path !== "" && !compiledDefault(path)))];
+	const host = (pick$1("hostname") ?? c.host).replace(/^.*@/, "");
+	const user = c.user ?? pick$1("user");
+	const portText = pick$1("port");
+	const port = c.port ?? (portText !== void 0 && /^\d+$/.test(portText) ? Number(portText) : void 0);
+	const proxyJumpRaw = c.proxyJump ?? pick$1("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
@@ -2015,12 +2092,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,
@@ -2045,6 +2126,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}` : "";
@@ -2381,6 +2475,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 §三"一层机械转义"）。 */
@@ -2460,6 +2644,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
@@ -3189,6 +3471,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;
@@ -3381,12 +3666,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"`;
@@ -3398,6 +3703,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));
@@ -3675,7 +4012,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);
@@ -3838,9 +4176,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; 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 = {}) {
@@ -3865,7 +4203,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",
@@ -3980,7 +4318,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) => [{
@@ -4026,6 +4368,7 @@ function createRemoteTool(driver, opts = {}) {
 						durationMs: Date.now() - start
 					};
 				}
+				const copyStart = Date.now();
 				const receipt = await driver.copy({
 					src: args.src,
 					dst: args.dst,
@@ -4035,12 +4378,14 @@ function createRemoteTool(driver, opts = {}) {
 					...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
 					...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
 				}, exec.signal, { sessionKey: getSessionKey(exec) });
+				const exits = receipt.exits ?? [];
+				if (exits.some((code) => code !== 0)) throw new Error(JSON.stringify(receipt));
 				return {
 					kind: "copy",
 					text: JSON.stringify(receipt),
 					receipt,
-					exit: null,
-					durationMs: 0
+					exit: exits.length > 0 ? 0 : null,
+					durationMs: Date.now() - copyStart
 				};
 			}
 			if ([
@@ -4126,6 +4471,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;
 		}
 	});
@@ -4150,7 +4496,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");
 }

package/remote/provenance.json

@@ -6,13 +6,14 @@
     "better-dsh/src/remote/agent-registration.ts": "459301354ea1ab713984bb01bc491a080256d4e983e55ff074e2665c3213d355",
     "better-dsh/src/remote/archive.ts": "fd32f96dc63421be7d56eb545badf355c6ee2498599605ffa48958b9efca9a63",
     "better-dsh/src/remote/copy.ts": "bd6f290d3f8ec3e33f9980f160b26390a3be38ead891b81de7cf610940a7af87",
-    "better-dsh/src/remote/driver.ts": "f56d68f0eded0f4c145f6442170630a5f38d2e2a340be717adc97380d5a463ce",
+    "better-dsh/src/remote/driver.ts": "ba44b100228e54681a243d4b739aba14d2b5efe98c238220f1029cf9afba5e2b",
     "better-dsh/src/remote/endpoints.ts": "315b6c37e6e5dbd51301aa971566b8345593560e1f2ba299e71143e147a8a17c",
     "better-dsh/src/remote/file-worker.ts": "31ac019a944cf7fdcd0ff044f8b330d923bf4d384c77056f9b7e3032bc8c9598",
+    "better-dsh/src/remote/helper.ts": "789a802610fc480bb1c922dd284787ca22d7394fa906c729ee33d78ade79973c",
     "better-dsh/src/remote/hub-contract.ts": "4bd333f3ef3e94305a64f04c03948a9dae4bbf5268b0d26d9de99770be2d8ac9",
     "better-dsh/src/remote/input.ts": "7e543adb0973c25cbd24103c2d838db0fdacdd32525278d789004fc237dcd924",
     "better-dsh/src/remote/jobs.ts": "9587f2694426fcf00ff33d9db164d5b15ea659aed7dbcb1df2640fa3f08b2149",
-    "better-dsh/src/remote/native-copy.ts": "49e1e1384c05637421f62d0eb562d9d5dfe00185ff2f6a15ae71d6881546d7fd",
+    "better-dsh/src/remote/native-copy.ts": "0c2045330c1007e49251643971d5edb9ef887a4964493450fd4184319d347b6e",
     "better-dsh/src/remote/nonce-framing.ts": "5592fec76cec0c1e1ac75f4806d0904cd111bf2061b1fada4f0dfa12014d1233",
     "better-dsh/src/remote/oneshot.ts": "99f2c809ba1159c7865ec3cff2e6d7b1f165a7f03185a6fc9505c1a534ba57bc",
     "better-dsh/src/remote/output-ring.ts": "a79104bd3dcddab06a3fe7e52d239a70becd4f2dcddd0c9b6513f5fe3c4ed0bc",
@@ -23,12 +24,12 @@
     "better-dsh/src/remote/rsync.ts": "21f10f0a24fd5148e298c938aaabeff85c96becc76317a1d3cc5c2e8a517c7c0",
     "better-dsh/src/remote/ssh-config.ts": "71ce833be5c934430e8a9ca982af055fccb71d6c3e64513ae83e7937b070e446",
     "better-dsh/src/remote/ssh-process.ts": "9b4d754af5af0fe6a903e683642e94842f8662358b72467d41f2288e1e67fd79",
-    "better-dsh/src/remote/ssh-rsync-native-relay.ts": "3376cd389f11c6057408709ac65a58c8922ba04fd0b226feff5be8a84b6b04b5",
+    "better-dsh/src/remote/ssh-rsync-native-relay.ts": "3a30f65f1c548badd1e8a6018c4f7cacd8f75e2aec4d7b7181b03fc04f180f27",
     "better-dsh/src/remote/ssh-targets.ts": "d463357d03fec88f9cdc3c47bba85ae9213f2641b2c08689fe9a7af42fe8bcd4",
     "better-dsh/src/remote/status.ts": "54264917bd50401c5a2f2ff9df325af7a5e790597e6307fcdc46a8455d18b530",
     "better-dsh/src/remote/target.ts": "965a04b3561aa56ee089876a869fd2116b1773ef34b053b3006905fcde063a43",
-    "better-dsh/src/remote/tool.ts": "a9a17c37a9554e1184a644160c5677eac08fced8e89358fce60092c86cfb142f",
-    "better-dsh/src/remote/transports.ts": "c7dbe00f827aee9925146667a9a9f331527c3c1867d6f7f2a0ceedebcce1e225",
+    "better-dsh/src/remote/tool.ts": "997edf11d0512866682ee87ddd0a6b5e060db0c222d97d7544b2a52a5e8749bc",
+    "better-dsh/src/remote/transports.ts": "258aa92224a310d632c53a326d2e3d3d2b0f0f1bf2f9ceeb554bded03581ae18",
     "better-dsh/third_party/schemastery/lib/index.cjs": "aca1c1a47c7b6034feee01501aefca3e6dd97a0bac4fe334fd30647ae5a9e480",
     "better-dsh/third_party/schemastery/lib/index.d.mts": "66847f605af58c42575333c825eefdec4ad38278ad6cb260e37aa0cc63803bbd",
     "better-dsh/third_party/schemastery/lib/index.mjs": "cfcbe46c7416bdb35ce891c252152bbf519e08199bede5930dd7cb880c65f1ef",
@@ -56,7 +57,16 @@
   },
   "outputs": {
     "file-worker.js": "f84f5b48de915949d85c3d0340a343cc5901218c3bc2dafdf5cecaa244f7b6e3",
-    "plugin.d.ts": "a1ea4b56c323bb1409c72160ccb75c54e6cfa73fb790505f51dce78caa148966",
-    "plugin.js": "c5ff1c08b5548609517adaec736238425ee1753a4b65385c226af581f3508f70"
+    "helper-bin/MANIFEST.json": "c8c13fffd331abbdcfb29783e2ebcbe1ba9737d56ed495df2d78788c6b6c7d94",
+    "helper-bin/aarch64-apple-darwin/BUILT-VER": "0d13f4cceb4520b0970f93ee648432615239279700de836661c63f2c89ac41dd",
+    "helper-bin/aarch64-apple-darwin/superd-run": "715c2d7bd935f3b4cc4ae0ffb10d3fab946bb62d93f592ccfe2a7446669ff76b",
+    "helper-bin/aarch64-unknown-linux-musl/BUILT-VER": "0d13f4cceb4520b0970f93ee648432615239279700de836661c63f2c89ac41dd",
+    "helper-bin/aarch64-unknown-linux-musl/superd-run": "22ac1c7f913092d8ca8d312b93528dd2263200f9670dc183fd215bc89d2bac68",
+    "helper-bin/x86_64-pc-windows-gnu/BUILT-VER": "0d13f4cceb4520b0970f93ee648432615239279700de836661c63f2c89ac41dd",
+    "helper-bin/x86_64-pc-windows-gnu/superd-run.exe": "a638479e1ccb1c4e185085100450962e39164158a76097b5087d2a3bb8880ac0",
+    "helper-bin/x86_64-unknown-linux-musl/BUILT-VER": "0d13f4cceb4520b0970f93ee648432615239279700de836661c63f2c89ac41dd",
+    "helper-bin/x86_64-unknown-linux-musl/superd-run": "79e42879509bb87d2fe9888d282151fd17113203d3172f59a16fcb5a180ba057",
+    "plugin.d.ts": "b58e5a7148767a28ecc87b4fe1a39ff287ddba5cf6d1e538f6242dfb4d0485f8",
+    "plugin.js": "d97c93d87242aaac376858206cd3407f4283dd9b0036a190329efb26e305a04a"
   }
 }