better-dsh 0.3.1-a → 0.3.1-b

package/lib/mobile/plugin.d.ts

@@ -1,5 +1,5 @@
 import { t as Schema } from "../index-DTDXUe6m.js";
-import { r as MobileConfig } from "../web-trust-C_Y6o8Z2.js";
+import { r as MobileConfig } from "../web-trust-Dej_RI2B.js";
 import { Context } from "@deepseek-ai/cordis";
 
 //#region src/mobile/plugin.d.ts

package/lib/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/lib/remote/helper-bin/aarch64-apple-darwin/BUILT-VER

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

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

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

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

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

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

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

package/lib/remote/plugin.d.ts

@@ -136,6 +136,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 {
@@ -210,6 +227,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;
@@ -234,6 +253,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 解析复用）。 */
@@ -250,6 +271,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?: {
@@ -273,6 +297,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/lib/remote/plugin.js

@@ -1,12 +1,13 @@
 import { t as Schema } from "../lib-C8_jXvwA.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, 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";
@@ -739,6 +740,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)
@@ -771,7 +773,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}`;
@@ -803,7 +805,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,13 +817,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}`
@@ -913,30 +920,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$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
@@ -1123,12 +1200,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 +1234,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}` : "";
@@ -1489,6 +1583,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 +1752,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 +2579,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;
@@ -2489,12 +2774,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 +2811,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 +3120,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 +3284,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 = {}) {
@@ -2973,7 +3311,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",
@@ -3088,7 +3426,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) => [{
@@ -3134,6 +3476,7 @@ function createRemoteTool(driver, opts = {}) {
 						durationMs: Date.now() - start
 					};
 				}
+				const copyStart = Date.now();
 				const receipt = await driver.copy({
 					src: args.src,
 					dst: args.dst,
@@ -3143,12 +3486,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 ([
@@ -3234,6 +3579,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;
 		}
 	});
@@ -3258,7 +3604,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/lib/url-schemes/index.d.ts

@@ -1,6 +1,6 @@
+import { t as Schema } from "../index-DTDXUe6m.js";
 import { Context } from "@deepseek-ai/cordis";
 import { ToolDefinition } from "@deepseek-ai/dsh-tools";
-import * as _deepseek_ai_schemastery11 from "@deepseek-ai/schemastery";
 
 //#region src/url-schemes/tools/write.d.ts
 
@@ -50,12 +50,12 @@ declare const inject: string[];
  * real patch-line config. Schema-level defaults (both ON — the service is
  * opt-out) survive every overlay layer, per the v0.2.2a ruling.
  */
-declare const Config: _deepseek_ai_schemastery11.default<Schemastery.ObjectS<NoInfer<{
-  urlSchemes: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
-  hashline: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
+declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+  urlSchemes: Schema<boolean, boolean, "defined">;
+  hashline: Schema<boolean, boolean, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
-  urlSchemes: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
-  hashline: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
+  urlSchemes: Schema<boolean, boolean, "defined">;
+  hashline: Schema<boolean, boolean, "defined">;
 }>>, "plain">;
 /** Register the four URL-aware tools on one agent's own scope layer. */
 /**
@@ -75,12 +75,12 @@ declare function apply(ctx: Context, config: UrlSchemesConfig | undefined): void
 declare const _default: {
   name: string;
   inject: string[];
-  Config: _deepseek_ai_schemastery11.default<Schemastery.ObjectS<NoInfer<{
-    urlSchemes: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
-    hashline: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
+  Config: Schema<Schemastery.ObjectS<NoInfer<{
+    urlSchemes: Schema<boolean, boolean, "defined">;
+    hashline: Schema<boolean, boolean, "defined">;
   }>>, Schemastery.ObjectT<NoInfer<{
-    urlSchemes: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
-    hashline: _deepseek_ai_schemastery11.default<boolean, boolean, "defined">;
+    urlSchemes: Schema<boolean, boolean, "defined">;
+    hashline: Schema<boolean, boolean, "defined">;
   }>>, "plain">;
   apply: typeof apply;
 };

package/lib/web-password.d.ts

@@ -1,7 +1,7 @@
+import { t as Schema } from "./index-DTDXUe6m.js";
 import { Context } from "@deepseek-ai/cordis";
 import { IncomingMessage } from "node:http";
 import { CredentialRecord } from "@deepseek-ai/dsh-credentials";
-import * as _deepseek_ai_schemastery21 from "@deepseek-ai/schemastery";
 
 //#region src/web-password.d.ts
 
@@ -123,10 +123,10 @@ interface WebPasswordConfig {
   /** Absolute browser-session lifetime in days. Default: 30 (the native default). */
   cookieMaxAgeDays?: number;
 }
-declare const Config: _deepseek_ai_schemastery21.default<Schemastery.ObjectS<NoInfer<{
-  cookieMaxAgeDays: _deepseek_ai_schemastery21.default<number, number, "defined">;
+declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+  cookieMaxAgeDays: Schema<number, number, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
-  cookieMaxAgeDays: _deepseek_ai_schemastery21.default<number, number, "defined">;
+  cookieMaxAgeDays: Schema<number, number, "defined">;
 }>>, "plain">;
 /** Cordis plugin name; also the scope of this row's credential record. */
 declare const name = "dashr-web-password";
@@ -145,10 +145,10 @@ declare function apply(ctx: Context, config?: WebPasswordConfig): void;
 declare const _default: {
   name: string;
   inject: string[];
-  Config: _deepseek_ai_schemastery21.default<Schemastery.ObjectS<NoInfer<{
-    cookieMaxAgeDays: _deepseek_ai_schemastery21.default<number, number, "defined">;
+  Config: Schema<Schemastery.ObjectS<NoInfer<{
+    cookieMaxAgeDays: Schema<number, number, "defined">;
   }>>, Schemastery.ObjectT<NoInfer<{
-    cookieMaxAgeDays: _deepseek_ai_schemastery21.default<number, number, "defined">;
+    cookieMaxAgeDays: Schema<number, number, "defined">;
   }>>, "plain">;
   apply: typeof apply;
 };

package/lib/{web-trust-C_Y6o8Z2.d.ts → web-trust-Dej_RI2B.d.ts}

@@ -1,5 +1,5 @@
+import { t as Schema } from "./index-DTDXUe6m.js";
 import { Context } from "@deepseek-ai/cordis";
-import * as _deepseek_ai_schemastery0 from "@deepseek-ai/schemastery";
 
 //#region src/web-trust.d.ts
 
@@ -76,12 +76,12 @@ interface TrustConfig {
   trustedPageAuthorities?: readonly string[];
 }
 /** Row config schema (schema-level default derives from `DSH_TRUSTED_HOSTS`). */
-declare const Config: _deepseek_ai_schemastery0.default<Schemastery.ObjectS<NoInfer<{
-  trustAllHosts: _deepseek_ai_schemastery0.default<boolean, boolean, "defined">;
-  trustedPageAuthorities: _deepseek_ai_schemastery0.default<string[], string[], "defined">;
+declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+  trustAllHosts: Schema<boolean, boolean, "defined">;
+  trustedPageAuthorities: Schema<string[], string[], "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
-  trustAllHosts: _deepseek_ai_schemastery0.default<boolean, boolean, "defined">;
-  trustedPageAuthorities: _deepseek_ai_schemastery0.default<string[], string[], "defined">;
+  trustAllHosts: Schema<boolean, boolean, "defined">;
+  trustedPageAuthorities: Schema<string[], string[], "defined">;
 }>>, "plain">;
 /** Cordis plugin name. */
 declare const name = "dashr-web-trust";
@@ -100,12 +100,12 @@ declare function apply(ctx: Context, config: TrustConfig | undefined): void;
 declare const _default: {
   name: string;
   inject: string[];
-  Config: _deepseek_ai_schemastery0.default<Schemastery.ObjectS<NoInfer<{
-    trustAllHosts: _deepseek_ai_schemastery0.default<boolean, boolean, "defined">;
-    trustedPageAuthorities: _deepseek_ai_schemastery0.default<string[], string[], "defined">;
+  Config: Schema<Schemastery.ObjectS<NoInfer<{
+    trustAllHosts: Schema<boolean, boolean, "defined">;
+    trustedPageAuthorities: Schema<string[], string[], "defined">;
   }>>, Schemastery.ObjectT<NoInfer<{
-    trustAllHosts: _deepseek_ai_schemastery0.default<boolean, boolean, "defined">;
-    trustedPageAuthorities: _deepseek_ai_schemastery0.default<string[], string[], "defined">;
+    trustAllHosts: Schema<boolean, boolean, "defined">;
+    trustedPageAuthorities: Schema<string[], string[], "defined">;
   }>>, "plain">;
   apply: typeof apply;
 };

package/lib/web-trust.d.ts

@@ -1,2 +1,3 @@
-import { a as _default, c as buildTrustScript, d as name, i as TrustConfig, l as deriveDefaultPageAuthorities, n as Config, o as apply, r as MobileConfig, s as buildMobileScript, t as BootScriptRow, u as inject } from "./web-trust-C_Y6o8Z2.js";
+import "./index-DTDXUe6m.js";
+import { a as _default, c as buildTrustScript, d as name, i as TrustConfig, l as deriveDefaultPageAuthorities, n as Config, o as apply, r as MobileConfig, s as buildMobileScript, t as BootScriptRow, u as inject } from "./web-trust-Dej_RI2B.js";
 export { BootScriptRow, Config, MobileConfig, TrustConfig, apply, buildMobileScript, buildTrustScript, _default as default, deriveDefaultPageAuthorities, inject, name };

package/lib/welcome-notice.d.ts

@@ -1,15 +1,15 @@
+import { t as Schema } from "./index-DTDXUe6m.js";
 import { Context } from "@deepseek-ai/cordis";
-import * as _deepseek_ai_schemastery9 from "@deepseek-ai/schemastery";
 
 //#region src/welcome-notice.d.ts
 declare const name = "dashr-welcome-notice";
 declare const inject: string[];
-declare const Config: _deepseek_ai_schemastery9.default<NoInfer<Schemastery.ObjectS<{}>>, NoInfer<Schemastery.ObjectT<{}>>, "volatile">;
+declare const Config: Schema<NoInfer<Schemastery.ObjectS<{}>>, NoInfer<Schemastery.ObjectT<{}>>, "volatile">;
 declare function apply(ctx: Context): void;
 declare const _default: {
   name: string;
   inject: string[];
-  Config: _deepseek_ai_schemastery9.default<NoInfer<Schemastery.ObjectS<{}>>, NoInfer<Schemastery.ObjectT<{}>>, "volatile">;
+  Config: Schema<NoInfer<Schemastery.ObjectS<{}>>, NoInfer<Schemastery.ObjectT<{}>>, "volatile">;
   apply: typeof apply;
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-dsh",
-  "version": "0.3.1-a",
+  "version": "0.3.1-b",
   "description": "Make your dsh ready for serious coding tasks. (Tools x Schemas)^REPL. `skill://`, `ctx://`, `agent://`, `dvc://`, `dsh://`, Python REPL, Context as Variables, cross compactions recallable, full context revive. `hash-edit`, `dvc://browser`, subagent as function, workflow as function.",
   "type": "module",
   "main": "lib/index.js",
@@ -75,7 +75,7 @@
   ],
   "scripts": {
     "prebuild": "node scripts/copy-docs.mjs",
-    "build": "tsdown && npm run build-client && node scripts/copy-kernel-bridge.mjs && node scripts/copy-ast-assets.mjs",
+    "build": "tsdown && npm run build-client && node scripts/copy-kernel-bridge.mjs && node scripts/copy-ast-assets.mjs && node scripts/copy-helper-bins.mjs",
     "typecheck": "npm run typecheck:host && npm run typecheck:client",
     "typecheck:host": "tsc --noEmit",
     "typecheck:client": "tsc -p tsconfig.client.json",