better-dsh 0.3.2 → 0.3.3-c

package/lib/remote/plugin.js

@@ -1,7 +1,8 @@
 import { t as Schema } from "../lib.js";
+import { createRequire } from "node:module";
 import { Context } from "@deepseek-ai/cordis";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { constants, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { constants, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -11,6 +12,7 @@ import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { createConnection, createServer } from "node:net";
+import { Buffer as Buffer$1 } from "node:buffer";
 
 //#region src/remote/archive.ts
 const FILE_FRAME_BYTES = 64 * 1024;
@@ -572,6 +574,15 @@ function startBinaryProcess(argv, options = {}) {
 	let diagnostic;
 	let timedOut = false, finished = false, cancelled = false;
 	let cleanup;
+	let cancelledNotified = false;
+	const notifyCancel = () => {
+		if (!cancelledNotified) {
+			cancelledNotified = true;
+			try {
+				options.onCancel?.();
+			} catch {}
+		}
+	};
 	let timer;
 	const signal = (sig) => {
 		if (child.pid === void 0) return false;
@@ -611,6 +622,7 @@ function startBinaryProcess(argv, options = {}) {
 	const cancel = () => {
 		if (!finished) {
 			cancelled = true;
+			notifyCancel();
 			reap();
 		}
 	};
@@ -1609,150 +1621,6 @@ function sshArgv(connection, options = {}) {
 	], options.extraArgs ?? [], options.command);
 }
 
-//#endregion
-//#region src/remote/input.ts
-/** Local carrier validation precedes any target discovery, connection or spawn. */
-async function prepareRemoteInput(input) {
-	if (input.mode !== void 0 && input.mode !== "oneshot" && input.mode !== "pty") throw new Error("[E_BAD_MODE] remote: mode must be oneshot or pty");
-	if (input.scriptPath !== void 0) {
-		if (input.cmd !== void 0 || input.stdin !== void 0 || input.mode === "pty" || input.spawn !== void 0) throw new Error("[E_SCRIPT_PARAMS] remote: script is oneshot-only and cannot be combined with cmd, stdin, spawn or PTY lanes");
-		if (typeof input.scriptPath !== "string" || !isAbsolute(input.scriptPath) || input.scriptPath.includes("\0")) throw new Error("[E_SCRIPT_PATH] remote: script must be a local absolute path without NUL");
-	}
-	if (!input.target && input.spawn === void 0 && input.ssh === void 0) throw new Error("[E_PARAMS] remote: target is required (spawn / ssh are BYO entry points and may stand alone)");
-	if (input.scriptPath !== void 0) {
-		let stdin;
-		try {
-			stdin = await readFile(input.scriptPath, "utf8");
-		} catch (error) {
-			throw new Error(`[E_SCRIPT_READ] remote: cannot read local script ${JSON.stringify(input.scriptPath)} — ${error instanceof Error ? error.message : String(error)}`);
-		}
-		return {
-			target: input.target,
-			ssh: input.ssh,
-			cmd: "bash -s",
-			stdin,
-			mode: "oneshot",
-			timeout: input.timeout
-		};
-	}
-	return {
-		target: input.target,
-		spawn: input.spawn,
-		ssh: input.ssh,
-		cmd: input.cmd ?? "",
-		stdin: input.stdin,
-		mode: input.mode,
-		timeout: input.timeout
-	};
-}
-
-//#endregion
-//#region src/remote/oneshot.ts
-async function runOneShot(argv, opts = {}) {
-	const process$1 = startOneShot(argv, opts);
-	const result = await process$1.done;
-	const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
-	return {
-		...result,
-		stdout: stdout.text,
-		stderr: [stderr.text, stderr.diagnostic].filter(Boolean).join("\n"),
-		outputStats: {
-			stdout: stdout.stats,
-			stderr: stderr.stats
-		}
-	};
-}
-
-//#endregion
-//#region src/remote/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 §三"一层机械转义"）。 */
@@ -1781,7 +1649,10 @@ bash -lc ${shQuote(cmd)}`;
 		wrapped
 	];
 	switch (plan.kind) {
-		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `setsid --wait bash -c ${shQuote(wrapped)}` });
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, {
+			command: `setsid --wait bash -c ${shQuote(wrapped)}`,
+			extraArgs: options.muxArgv
+		});
 		case "docker": return [
 			"docker",
 			"exec",
@@ -1835,21 +1706,41 @@ function buildSpawnArgv(spawnCommand) {
 		"/dev/null"
 	];
 }
+/** Hub PTY（0.3.2-c；0.3.2-d F4 修正）：会话子进程 = 本地 `script` PTY 托管的 WS 字节泵
+*  （hub-pty-pump.mjs）。与 docker exec 的嵌套 PTY 同形，但泵是哑 node 子进程、不像
+*  `ssh -tt` / `docker exec -it` 那样作为前台子进程自己把本地 tty 置 raw——所以本地包装必须
+*  `stty raw`：canonical+ISIG 下 0x03 在本地变 SIGINT 杀泵、0x04 变 EOF 结束泵 stdin
+*  （F4：input ^C/^D 与 job_kill 会打死整条会话）。raw 只作用于本地半段；对端 script PTY
+*  保持 canonical，^C/^D 在对端产生 SIGINT/EOF 正是我们要的语义（字节原样过线，解释权在
+*  对端）。kill 链 session 组杀 → 泵死 → WS 关 → 对端组杀，双向自然闭合。连接事实走 wrapper
+*  内 env 赋值（cookie 不进 argv、不落 ps）。 */
+function buildHubPtyArgv(endpoint, assets) {
+	const node = assets.nodePath ?? process.execPath;
+	return [
+		"script",
+		"-qfec",
+		`stty raw -echo 2>/dev/null ; ${`export SUPERD_HUB_PTY_URL=${shQuote(endpoint.url)} SUPERD_HUB_PTY_COOKIE=${shQuote(endpoint.cookie)} SUPERD_HUB_PTY_WS=${shQuote(endpoint.wsPath)}`} ; exec ${shQuote(node)} ${shQuote(assets.pumpPath)}`,
+		"/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) {
+function buildHelperProbeArgv(plan, assets, muxArgv) {
 	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`);
+	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`, muxArgv);
 }
-function buildHelperUploadArgv(plan, triple, file, assets) {
+function buildHelperUploadArgv(plan, triple, file, assets, muxArgv) {
 	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}"`);
+	return helperShellArgv(plan, `mkdir -p "${dir}" && cat > "${dir}/${file}.tmp" && chmod 0755 "${dir}/${file}.tmp" && mv -f "${dir}/${file}.tmp" "${dir}/${file}"`, muxArgv);
 }
 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 "ssh": return sshArgv(plan.connection ?? { host: plan.host }, {
+			command: `exec ${shQuote(binPath)} run --tag ${shQuote(tag)} -- bash -lc ${shQuote(cmd)}`,
+			extraArgs: options.muxArgv
+		});
 		case "docker": return [
 			"docker",
 			"exec",
@@ -1882,9 +1773,12 @@ function buildHelperOneShotArgv(plan, binPath, options) {
 		];
 	}
 }
-function buildHelperKillgroupArgv(plan, binPath, tag) {
+function buildHelperKillgroupArgv(plan, binPath, tag, muxArgv) {
 	switch (plan.kind) {
-		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `${shQuote(binPath)} killgroup --tag ${shQuote(tag)}` });
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, {
+			command: `${shQuote(binPath)} killgroup --tag ${shQuote(tag)}`,
+			extraArgs: muxArgv
+		});
 		case "docker": return [
 			"docker",
 			"exec",
@@ -1908,9 +1802,12 @@ function buildHelperKillgroupArgv(plan, binPath, tag) {
 		];
 	}
 }
-function helperShellArgv(plan, script) {
+function helperShellArgv(plan, script, muxArgv) {
 	switch (plan.kind) {
-		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: script });
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, {
+			command: script,
+			extraArgs: muxArgv
+		});
 		case "docker": return [
 			"docker",
 			"exec",
@@ -1935,108 +1832,347 @@ function helperShellArgv(plan, script) {
 }
 
 //#endregion
-//#region src/remote/nonce-framing.ts
-/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
-function genNonce(bytes = 8) {
-	return randomBytes(bytes).toString("hex");
-}
-/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
-function wrapPtyCommand(cmd, nonce) {
-	return `{\n${cmd}\n} ; __superd_e=$? ; printf '\\033]133;E;${nonce};%s\\007' "$(env -0 | base64 | tr -d '\\n\\r')" ; printf '\\033]133;D;${nonce};%s;%s\\007' "$__superd_e" "$PWD" ; unset __superd_e\n`;
-}
-/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
-function buildInitCommand(nonce) {
-	return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;E;${nonce};%s\\007' "$(env -0 | base64 | tr -d '\\n\\r')" ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
-}
-const ANSI_RE = /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)?|\[[0-9;?]*[ -/]*[@-~]|[@-Z\\-_])/g;
-function stripAnsi(s) {
-	return s.replace(ANSI_RE, "");
-}
-function normalizePtyText(s) {
-	return stripAnsi(s).replace(/\r\n/g, "\n").replace(/\r/g, "");
-}
-function tailWindow(text, cap, stats) {
-	let tail = text.slice(-cap);
-	if (tail.charCodeAt(0) >= 56320 && tail.charCodeAt(0) <= 57343) tail = tail.slice(1);
-	const returned = stats?.unit === "bytes" ? Buffer.byteLength(tail) : tail.length;
-	const total = stats?.total ?? text.length;
-	const updated = stats === void 0 ? {} : { stats: {
-		...stats,
-		returned
-	} };
-	if (total <= returned) return {
-		text: tail,
-		...updated
-	};
+//#region src/remote/input.ts
+/** Local carrier validation precedes any target discovery, connection or spawn. */
+async function prepareRemoteInput(input) {
+	if (input.mode !== void 0 && input.mode !== "oneshot" && input.mode !== "pty") throw new Error("[E_BAD_MODE] remote: mode must be oneshot or pty");
+	if (input.scriptPath !== void 0) {
+		if (input.cmd !== void 0 || input.spawn !== void 0) throw new Error("[E_SCRIPT_PARAMS] remote: script and cmd are alternative carriers — pass one; spawn belongs to BYO PTY creation, not scripts");
+		if (typeof input.scriptPath !== "string" || !isAbsolute(input.scriptPath) || input.scriptPath.includes("\0")) throw new Error("[E_SCRIPT_PATH] remote: script must be a local absolute path without NUL");
+	}
+	if (!input.target && input.spawn === void 0 && input.ssh === void 0) throw new Error("[E_PARAMS] remote: target is required (spawn / ssh are BYO entry points and may stand alone)");
+	if (input.scriptPath !== void 0) {
+		let script;
+		try {
+			script = await readFile(input.scriptPath, "utf8");
+		} catch (error) {
+			throw new Error(`[E_SCRIPT_READ] remote: cannot read local script ${JSON.stringify(input.scriptPath)} — ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (script.includes("\0")) throw new Error("[E_SCRIPT_NUL] remote: script contains NUL bytes — the command channel cannot carry it; transfer the file and run it with cmd instead");
+		return {
+			target: input.target,
+			ssh: input.ssh,
+			cmd: `bash -c ${shQuote(script)}`,
+			stdin: input.stdin,
+			mode: input.mode,
+			timeout: input.timeout
+		};
+	}
 	return {
-		text: `[truncated: showing last ${returned} of ${total} ${stats?.unit === "bytes" ? "bytes" : "chars"}${stats !== void 0 && stats.dropped > 0 ? `; retained ${stats.retained}, dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === "bytes" ? "bytes" : "UTF-16 code units"}` : ""}]\n${tail}`,
-		truncated: total,
-		...updated
+		target: input.target,
+		spawn: input.spawn,
+		ssh: input.ssh,
+		cmd: input.cmd ?? "",
+		stdin: input.stdin,
+		mode: input.mode,
+		timeout: input.timeout
 	};
 }
-const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/;
-const ENV_BODY_RE = /^([A-Za-z0-9+/=]*)\x07/;
-/**
-* 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
-* 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
-* 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
-*/
-function createNonceFrameParser(nonce, events) {
-	const prefix = `\x1b]133;D;${nonce};`;
-	const prefixE = `\x1b]133;E;${nonce};`;
-	const prefixes = [prefix, prefixE];
-	let buf = "";
-	let done = false;
-	const emit = (raw) => {
-		const text = normalizePtyText(raw);
-		if (text.length > 0) events.onOutput?.(text);
-	};
-	/** 缓冲尾若是任一候选前缀的真前缀则扣留（D/E 共用）；flush() 放出残余。 */
-	const holdback = () => {
-		let best = 0;
-		for (const p of prefixes) {
-			const max = Math.min(buf.length, p.length - 1);
-			for (let k = max; k > best; k--) if (buf.endsWith(p.slice(0, k))) {
-				best = k;
-				break;
-			}
+
+//#endregion
+//#region src/remote/oneshot.ts
+async function runOneShot(argv, opts = {}) {
+	const process$1 = startOneShot(argv, opts);
+	const result = await process$1.done;
+	const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
+	return {
+		...result,
+		stdout: stdout.text,
+		stderr: [stderr.text, stderr.diagnostic].filter(Boolean).join("\n"),
+		outputStats: {
+			stdout: stdout.stats,
+			stderr: stderr.stats
 		}
-		return best;
 	};
-	/** 扫描最早出现的帧：E（env 侧信道）先于 D 下发；D = settle，帧后字节丢弃。 */
-	const consume = () => {
-		if (done) return;
-		let idx = -1;
-		let isEnv = false;
-		for (const p of prefixes) {
-			const i = buf.indexOf(p);
-			if (i >= 0 && (idx === -1 || i < idx)) {
-				idx = i;
-				isEnv = p === prefixE;
-			}
-		}
-		if (idx < 0) {
-			const keep = holdback();
-			emit(buf.slice(0, buf.length - keep));
-			buf = buf.slice(buf.length - keep);
-			return;
-		}
-		emit(buf.slice(0, idx));
-		const rest = buf.slice(idx + (isEnv ? prefixE.length : prefix.length));
-		if (isEnv) {
-			const m$1 = ENV_BODY_RE.exec(rest);
-			if (m$1 === null) {
-				buf = buf.slice(idx);
-				return;
+}
+
+//#endregion
+//#region src/remote/helper.ts
+/** Reads helper-bin/MANIFEST.json next to the compiled module (lib/remote in
+* the npm package). 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, muxArgv = []) {
+		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, muxArgv).catch(() => null);
+			entry.catch(() => {});
+			this.states.set(key, entry);
+		}
+		return entry;
+	}
+	async bootstrap(plan, muxArgv) {
+		const { manifest } = this.assets;
+		const first = await this.exec(this.probeArgv(plan, this.assets, muxArgv), { 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, muxArgv), {
+			stdin: binary,
+			timeoutSec: 60
+		})).exit !== 0) return null;
+		const second = await this.exec(this.probeArgv(plan, this.assets, muxArgv), { 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/ssh-mux.ts
+/** SSH oneshot 连接复用（plan 2026-11-01 Task E；探针基线 = 发起端 OpenSSH 10.2p1，2026-11-01 实测）：
+*  - master 与客户端完全脱钩（fork 后 PPID=init、自有 pgid/session）→ 本地 killpg 取消/超时永不波及
+*    master，后续 oneshot 继续复用；这正好落在 startBinaryProcess 的组杀清理语义之内。
+*  - ControlPersist 到期 master 自行退出并 unlink socket；`ssh -O exit` 主动拆除亦同。
+*  - master 被 SIGKILL 会留下残 socket 文件：ControlMaster=auto 的下一个客户端会自愈重建
+*    （实测 exit 0），失败语义按 ssh 真实回退，不冒充复用。
+*  - 只注入 SSH oneshot 执行链（POSIX wrapper / helper probe·upload·run·killgroup / cleanup /
+*    status 探测）；PTY、scp、rsync、relay 与 copy 的 mkdir pre-hop 一律不注入。
+*  - CLI `-o` 覆盖用户 config 同名项是 OpenSSH 语义（last-option-wins），其余身份选项照常读 config。 */
+const SSH_MUX_CONTROL_PERSIST_SEC = 600;
+/** Linux sun_path 上限 108；留余量并在超限时诚实退化为不复用（MUX 是优化，不是前提）。 */
+const MAX_SOCKET_PATH = 104;
+function identityKey(identity) {
+	const c = identity.connection;
+	const raw = JSON.stringify([
+		identity.target,
+		c.host,
+		c.user ?? null,
+		c.port ?? null,
+		c.key ?? null,
+		c.proxyJump ?? null
+	]);
+	return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+/** 每 Agent 一个（driver 私有）：tool-owned 0700 socket 目录 + 按连接身份的 socket 名。
+*  目录名含随机 owner 后缀，跨 Agent 天然不共享；dispose 逐 socket `-O exit` 后整目录删除。 */
+var SshMux = class {
+	persistSec;
+	rootDir;
+	runner;
+	owner = randomUUID().slice(0, 8);
+	sockets = /* @__PURE__ */ new Map();
+	dir;
+	disposal;
+	constructor(options = {}) {
+		this.persistSec = options.persistSec ?? SSH_MUX_CONTROL_PERSIST_SEC;
+		this.rootDir = options.rootDir ?? tmpdir();
+		this.runner = options.runner ?? runOneShot;
+	}
+	/** 注入 SSH argv 的 MUX 选项（trusted internal argv，非模型输入）。目录懒建（纯 docker/hub
+	*  Agent 永不触盘）；超限/已 dispose 返回 [] = 诚实退化为普通连接。 */
+	argvFor(identity) {
+		if (this.disposal !== void 0) return [];
+		const socket = join(this.dir ?? (this.dir = join(this.rootDir, `superd-mux-${this.owner}`)), identityKey(identity));
+		if (socket.length + 1 > MAX_SOCKET_PATH) return [];
+		try {
+			mkdirSync(this.dir, {
+				recursive: true,
+				mode: 448
+			});
+		} catch {
+			return [];
+		}
+		this.sockets.set(socket, identity.connection.host);
+		return [
+			"-o",
+			`ControlPath=${socket}`,
+			"-o",
+			"ControlMaster=auto",
+			"-o",
+			`ControlPersist=${this.persistSec}`
+		];
+	}
+	/** Teardown：先 `-O exit` 逐 socket 礼貌拆除 master（不拨号、5s 上限、错误全吞——
+	*  master 已死/残 socket 属正常），再删目录。单飞（重复调用同一 Promise）。 */
+	dispose() {
+		if (this.disposal !== void 0) return this.disposal;
+		const sockets = [...this.sockets.entries()];
+		this.sockets.clear();
+		return this.disposal = (async () => {
+			await Promise.allSettled(sockets.map(([socket, host]) => this.runner([
+				"ssh",
+				"-o",
+				`ControlPath=${socket}`,
+				"-O",
+				"exit",
+				"--",
+				host
+			], { timeoutSec: 5 })));
+			if (this.dir !== void 0) try {
+				rmSync(this.dir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+		})();
+	}
+};
+
+//#endregion
+//#region src/remote/nonce-framing.ts
+/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
+function genNonce(bytes = 8) {
+	return randomBytes(bytes).toString("hex");
+}
+/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
+function wrapPtyCommand(cmd, nonce) {
+	return `{\n${cmd}\n} ; __superd_e=$? ; printf '\\033]133;E;${nonce};%s\\007' "$(env -0 | base64 | tr -d '\\n\\r')" ; printf '\\033]133;D;${nonce};%s;%s\\007' "$__superd_e" "$PWD" ; unset __superd_e\n`;
+}
+/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
+function buildInitCommand(nonce) {
+	return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;E;${nonce};%s\\007' "$(env -0 | base64 | tr -d '\\n\\r')" ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
+}
+const ANSI_RE = /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)?|\[[0-9;?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+function stripAnsi(s) {
+	return s.replace(ANSI_RE, "");
+}
+function normalizePtyText(s) {
+	return stripAnsi(s).replace(/\r\n/g, "\n").replace(/\r/g, "");
+}
+/** 0.3.2-e：自有 30K 返回窗口已删（原生 agent runtime 的 spill/输出保护接管模型上下文
+* 尺寸）。本 helper 只做 retention 披露：ring 留存（4M UTF-16 / 4MiB bytes）未驱逐时
+* 全量透传（returned=retained，无 banner）；驱逐（dropped>0，仅 >4M 输出发生）时打一行
+* banner 且 truncated=原始总量。text 已是 ring 尾部，不再二次裁剪。 */
+function disclose(text, stats) {
+	if (stats === void 0) return { text };
+	const returned = stats.retained;
+	const updated = { stats: {
+		...stats,
+		returned
+	} };
+	if (stats.dropped <= 0) return {
+		text,
+		...updated
+	};
+	const unit = stats.unit === "bytes" ? "bytes" : "chars";
+	return {
+		text: `[retention tail: showing last ${stats.retained} of ${stats.total} ${unit}; dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === "bytes" ? "bytes" : "UTF-16 code units"}]\n${text}`,
+		truncated: stats.total,
+		...updated
+	};
+}
+const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/;
+const ENV_BODY_RE = /^([A-Za-z0-9+/=]*)\x07/;
+/**
+* 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
+* 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
+* 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
+*/
+function createNonceFrameParser(nonce, events) {
+	const prefix = `\x1b]133;D;${nonce};`;
+	const prefixE = `\x1b]133;E;${nonce};`;
+	const prefixes = [prefix, prefixE];
+	let buf$1 = "";
+	let done = false;
+	const emit = (raw) => {
+		const text = normalizePtyText(raw);
+		if (text.length > 0) events.onOutput?.(text);
+	};
+	/** 缓冲尾若是任一候选前缀的真前缀则扣留（D/E 共用）；flush() 放出残余。 */
+	const holdback = () => {
+		let best = 0;
+		for (const p of prefixes) {
+			const max = Math.min(buf$1.length, p.length - 1);
+			for (let k = max; k > best; k--) if (buf$1.endsWith(p.slice(0, k))) {
+				best = k;
+				break;
+			}
+		}
+		return best;
+	};
+	/** 扫描最早出现的帧：E（env 侧信道）先于 D 下发；D = settle，帧后字节丢弃。 */
+	const consume = () => {
+		if (done) return;
+		let idx = -1;
+		let isEnv = false;
+		for (const p of prefixes) {
+			const i = buf$1.indexOf(p);
+			if (i >= 0 && (idx === -1 || i < idx)) {
+				idx = i;
+				isEnv = p === prefixE;
+			}
+		}
+		if (idx < 0) {
+			const keep = holdback();
+			emit(buf$1.slice(0, buf$1.length - keep));
+			buf$1 = buf$1.slice(buf$1.length - keep);
+			return;
+		}
+		emit(buf$1.slice(0, idx));
+		const rest = buf$1.slice(idx + (isEnv ? prefixE.length : prefix.length));
+		if (isEnv) {
+			const m$1 = ENV_BODY_RE.exec(rest);
+			if (m$1 === null) {
+				buf$1 = buf$1.slice(idx);
+				return;
 			}
 			if (m$1[1].length > 0) events.onEnv?.(m$1[1]);
-			buf = rest.slice(m$1[0].length);
+			buf$1 = rest.slice(m$1[0].length);
 			consume();
 			return;
 		}
 		const m = FRAME_BODY_RE.exec(rest);
 		if (m === null) {
-			buf = buf.slice(idx);
+			buf$1 = buf$1.slice(idx);
 			return;
 		}
 		events.onFrame({
@@ -2044,16 +2180,16 @@ function createNonceFrameParser(nonce, events) {
 			cwd: m[2].length > 0 ? m[2] : null
 		});
 		done = true;
-		buf = "";
+		buf$1 = "";
 	};
 	return {
 		feed(chunk) {
-			buf += chunk;
+			buf$1 += chunk;
 			consume();
 		},
 		flush() {
-			if (buf.length > 0) events.onOutput?.(buf);
-			buf = "";
+			if (buf$1.length > 0) events.onOutput?.(buf$1);
+			buf$1 = "";
 		}
 	};
 }
@@ -2096,6 +2232,67 @@ function diffEnv(prev, next) {
 	};
 }
 
+//#endregion
+//#region src/remote/trace.ts
+/**
+* R1 定位轮插桩（2026-11-01）：`SUPERD_REMOTE_TRACE=<file>` 时输出 JSONL 事件，否则全 no-op。
+* 动机：rig-only「PTY background + startup stdin」丢失只在 rig 长驻进程复现（bg-read 形状 13/13），
+* 本地全组合 0 复现——必须在实际 rig 宿主进程内拿到第一手事件流。
+*
+* 设计约束：
+*  - 热路径（write/onOutput）零同步 IO：事件先进内存缓冲，异步 flush（settle/dispose/满 200 条）。
+*  - env 未设置时每个入口都是一次函数调用 + 立即 return，不改变交付语义。
+*  - 失败静默（trace 永不破坏工具行为）；缓冲上限 5000 条防失控。
+*/
+const TRACE_PATH = process.env.SUPERD_REMOTE_TRACE ?? "";
+const ENABLED = TRACE_PATH !== "";
+let buf = [];
+let flushing = false;
+function serialize(ev, fields) {
+	let s;
+	try {
+		s = JSON.stringify({
+			t: Date.now(),
+			mono: Number(process.hrtime.bigint() / 1000000n),
+			ev,
+			...fields
+		});
+	} catch {
+		s = JSON.stringify({
+			t: Date.now(),
+			ev,
+			err: "unserializable-fields"
+		});
+	}
+	return s ?? `{\"t\":${Date.now()},\"ev\":${JSON.stringify(ev)},\"err\":\"null\"}`;
+}
+function trace(ev, fields = {}) {
+	if (!ENABLED) return;
+	buf.push(serialize(ev, fields));
+	if (buf.length > 5e3) buf.splice(0, buf.length - 5e3);
+	if (buf.length >= 200) traceFlush();
+}
+async function traceFlush() {
+	if (!ENABLED || flushing || buf.length === 0) return;
+	flushing = true;
+	const out = buf.splice(0).join("\n") + "\n";
+	try {
+		const [{ appendFile }, { dirname: dirname$1 }] = await Promise.all([import("node:fs/promises"), import("node:path")]);
+		const dir = dirname$1(TRACE_PATH);
+		try {
+			await (await import("node:fs/promises")).mkdir(dir, { recursive: true });
+		} catch {}
+		await appendFile(TRACE_PATH, out);
+	} catch {}
+	flushing = false;
+	if (buf.length > 0) traceFlush();
+}
+/** 事件里的字节安全截断表示（JSON 转义 + 长度上限）。 */
+function traceRepr(s, max) {
+	const j = JSON.stringify(s) ?? "null";
+	return j.length > max ? `${j.slice(0, max)}…` : j;
+}
+
 //#endregion
 //#region src/remote/pty-session.ts
 /** spec §五.2 逐字。 */
@@ -2107,29 +2304,27 @@ function displayKey(key) {
 	const raw = key.includes("|") ? key.slice(key.indexOf("|") + 1) : key;
 	return raw.startsWith("p:") ? `pty:${raw.slice(2)}` : raw;
 }
-const LEDGER_MAX = 20;
-const summaryOf = (cmd) => {
-	const first = cmd.trim().split(/\r?\n/, 1)[0] ?? "";
-	return first.length > 72 ? `${first.slice(0, 71)}…` : first;
-};
 const DEFAULT_INIT_TIMEOUT_SEC = 30;
 const INTERRUPT_GRACE_MS = 3e3;
+/** F2（0.3.2-d）：\x03 触发 ISIG 时内核 flush 输入队列——130-marker 必须等 flush 完成
+* 再入队，否则首字节被吞（实测 'rintf' not found → 会话死）。 */
+const MARKER_SETTLE_MS = 80;
 /** pty 收集内存安全帽（Ruling P15，与 oneshot HARD_CAP 对齐）：模型面只见尾窗，保留尾部。 */
 const OUTPUT_HARD_CAP = 4e6;
 var PtySession = class {
 	proc = null;
 	state = "cold";
 	startPromise = null;
-	queue = Promise.resolve();
 	idleTimer = null;
 	onChunk = null;
 	deathWaiters = [];
 	diag = "";
 	inFlight = 0;
+	cmdSeq = 0;
 	/** P4/P5：当前占用前台的 detached job（background/超时 handoff）。非 null 时新命令拒绝（Q6）。 */
 	detachedJob = null;
-	/** 账本（§5）：本会话最近 20 条命令（FIFO，超出丢最旧）。 */
-	ledger = [];
+	/** §3.2（2026-10-25）：当前占用会话的命令——dispatch 同步占位，settle/cleanup 释放；input 的唯一写入对象。 */
+	activeCommand = null;
 	/** env 侧信道基线（init E 帧）；undefined = 侧信道不可用（不报假 delta）。 */
 	envBaseline;
 	/** idle 起点（ready / settle 时重置）；null = 尚无 idle 时钟（cold 或已 dispose）。 */
@@ -2160,10 +2355,13 @@ var PtySession = class {
 	get detachedCommandId() {
 		return this.detachedJob?.commandId ?? null;
 	}
-	/** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId，账本如实记录两者）。 */
+	/** handoff/card 面（2026-11-01 默认 PTY 轮）：当前占用会话的命令与可选 job 句柄；无 = null。 */
+	get active() {
+		return this.activeCommand === null ? null : { ...this.activeCommand };
+	}
+	/** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId）；运行中的命令同步携带（stdin-only 写入回执用）。 */
 	attachJob(commandId, jobId) {
-		const entry = [...this.ledger].reverse().find((e) => e.commandId === commandId);
-		if (entry !== void 0) entry.jobId = jobId;
+		if (this.activeCommand !== null && this.activeCommand.commandId === commandId) this.activeCommand.jobId = jobId;
 	}
 	/** Workbench 身份（§3）：id + 可选 label + connection + byo 标记。 */
 	get identity() {
@@ -2175,10 +2373,6 @@ var PtySession = class {
 			builtOn: this.opts.builtOn === true
 		};
 	}
-	/** 账本快照（session card 面，只读）。 */
-	ledgerSnapshot() {
-		return this.ledger;
-	}
 	/** spawn 创建原文（仅 BYO 会话；v2 起仅存档，不参与复用判定）。 */
 	get origin() {
 		return this.opts.origin;
@@ -2197,36 +2391,67 @@ var PtySession = class {
 	async warm() {
 		await this.start();
 	}
-	/** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。P4/P5（2026-10-19）：超时不再自动
-	* 打断——handoff 成 running job（byte-cursor 轮询 + 显式 interrupt，P8 机制原样保留在
-	* job.interrupt）；background 选项让 dispatch 立即回执。占用者是 detached job 时新命令
-	* 拒绝（Q6：诚实回状态优先于排队），纯同步并发 FIFO 语义不变。 */
+	/** 同一会话命令占位制（2026-10-25 interactive-stdin 轮）：dispatch 入口**同步**建立
+	* 命令占位（activeCommand + inFlight + 账本条目）——上一条命令仍在运行（同步等待 /
+	* 等输入 / detached job）时新 cmd 立即 E_SESSION_BUSY；原「纯同步并发排 FIFO」语义
+	* 废除（排队会让等输入的命令与补输入动作互相卡死，也给 busy 留下绕行窗口）。
+	* P4/P5：超时不杀命令而是 handoff 成 running job；background 立即回执；P8 显式
+	* interrupt 保留在 job.interrupt；死亡/冷态先重启（reconnect 语义不变）。 */
 	dispatch(cmd, dOpts) {
+		if (this.state === "disposed") return Promise.reject(/* @__PURE__ */ new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`));
+		if (this.activeCommand !== null) {
+			const handle = this.activeCommand.jobId ?? this.activeCommand.commandId;
+			return Promise.reject(/* @__PURE__ */ new Error(`[E_SESSION_BUSY] remote: pty session '${this.opts.id}' still runs a command (${this.activeCommand.commandId}) — feed it more stdin with {action:"exec", target:..., stdin:...} (stdin-only write), follow its output via job_output ${handle} (a synchronous exec hands its job off there on timeout), cancel with job_kill ${handle}, or address other work to another session / oneshot`));
+		}
+		const commandId = dOpts.commandId;
+		this.activeCommand = {
+			commandId,
+			...dOpts.jobId !== void 0 ? { jobId: dOpts.jobId } : {}
+		};
+		this.inFlight++;
+		this.cmdSeq++;
 		const attempt = async () => {
 			const started = Date.now();
 			const reconnected = this.state === "dead";
-			if (this.state !== "ready") await this.start();
-			if (this.state === "disposed") throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`);
-			if (this.detachedJob !== null) throw new Error(`[E_SESSION_BUSY] remote: pty session '${this.opts.id}' still runs a detached command (${this.detachedJob.commandId}) — poll job_output ${this.detachedJob.commandId}, cancel with job_kill ${this.detachedJob.commandId}, or address other work to another session / oneshot`);
-			const commandId = dOpts.commandId;
-			const entry = {
-				commandId,
-				summary: summaryOf(cmd),
-				exit: null,
-				durationMs: 0,
-				running: true
+			/** 占位撤销：命令从未真正启动（建连失败 / 建连中被 dispose）——释放 busy 与计数，
+			* 撤掉账本条目（与旧时序等价：条目原本在 start 成功之后才建立）。 */
+			const abandon = () => {
+				this.activeCommand = null;
+				this.inFlight--;
 			};
-			this.ledger.push(entry);
-			if (this.ledger.length > LEDGER_MAX) this.ledger.shift();
-			this.inFlight++;
+			if (this.state !== "ready") try {
+				await this.start();
+			} catch (error) {
+				abandon();
+				throw error;
+			}
+			if (this.state === "disposed") {
+				abandon();
+				throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`);
+			}
 			return await new Promise((resolve$1) => {
 				const nonce = genNonce();
 				const ring = new Utf16TailRing(OUTPUT_HARD_CAP);
+				let traceChunkSeq = 0;
+				trace("disp", {
+					s: this.opts.id,
+					key: this.opts.key,
+					commandId,
+					bg: dOpts.background === true,
+					stdinGiven: dOpts.stdin !== void 0,
+					cmdLen: cmd.length,
+					stdinLen: dOpts.stdin?.length ?? 0,
+					cmdRepr: traceRepr(cmd, 140),
+					stdinRepr: traceRepr(dOpts.stdin ?? "", 60),
+					state: this.state,
+					priorCmds: this.cmdSeq
+				});
 				let interrupted = false;
 				let settled = false;
 				let jobSettled = false;
 				let interruptTimer;
 				let killTimer;
+				let markerTimer;
 				let jobDone = null;
 				let envNext;
 				const detach = () => {
@@ -2243,6 +2468,13 @@ var PtySession = class {
 					};
 					this.detachedJob = job;
 					settled = true;
+					trace("detach", {
+						s: this.opts.id,
+						commandId,
+						outLen: ring.text.length,
+						tail: traceRepr(ring.text, 220)
+					});
+					traceFlush();
 					resolve$1({
 						output: ring.text,
 						outputStats: { stdout: ring.stats() },
@@ -2260,13 +2492,25 @@ var PtySession = class {
 				const cleanup = () => {
 					this.onChunk = null;
 					this.detachedJob = null;
+					this.activeCommand = null;
 					this.deathWaiters = this.deathWaiters.filter((w) => w !== deathWaiter);
 					if (interruptTimer !== void 0) clearTimeout(interruptTimer);
 					if (killTimer !== void 0) clearTimeout(killTimer);
+					if (markerTimer !== void 0) clearTimeout(markerTimer);
 				};
 				const settle = (r) => {
 					if (jobSettled) return;
 					jobSettled = true;
+					trace("settle", {
+						s: this.opts.id,
+						commandId,
+						exit: r.exit,
+						timedOut: r.timedOut,
+						cwd: r.cwd,
+						outLen: r.output.length,
+						tail: traceRepr(r.output, 260)
+					});
+					traceFlush();
 					cleanup();
 					this.inFlight--;
 					this.idleSince = Date.now();
@@ -2274,9 +2518,6 @@ var PtySession = class {
 					if (r.cwd !== null) this.lastCwdSeen = r.cwd;
 					const envDelta = envNext !== void 0 ? diffEnv(this.envBaseline, envNext) : void 0;
 					if (envNext !== void 0) this.envBaseline = envNext;
-					entry.exit = r.exit;
-					entry.durationMs = Date.now() - started;
-					entry.running = false;
 					const full = {
 						...r,
 						outputStats: { stdout: ring.stats() },
@@ -2302,6 +2543,13 @@ var PtySession = class {
 				const parser = createNonceFrameParser(nonce, {
 					onOutput: (t) => {
 						ring.push(t);
+						if (traceChunkSeq < 60) trace("out", {
+							s: this.opts.id,
+							commandId,
+							n: traceChunkSeq++,
+							len: t.length,
+							text: traceRepr(t, 180)
+						});
 					},
 					onEnv: (b64) => {
 						const m = decodeEnvSnapshot(b64);
@@ -2317,7 +2565,9 @@ var PtySession = class {
 				const twoStage = () => {
 					interrupted = true;
 					this.write("");
-					this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					markerTimer = setTimeout(() => {
+						this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					}, MARKER_SETTLE_MS);
 					killTimer = setTimeout(() => {
 						this.killTree();
 						this.markDead();
@@ -2330,8 +2580,41 @@ var PtySession = class {
 					}, INTERRUPT_GRACE_MS);
 				};
 				this.onChunk = (c) => parser.feed(c);
-				this.write(wrapPtyCommand(cmd, nonce));
-				if (dOpts.stdin !== void 0) this.write(dOpts.stdin);
+				const startup = dOpts.stdin === void 0 ? wrapPtyCommand(cmd, nonce) : wrapPtyCommand(cmd, nonce) + dOpts.stdin;
+				const wStdin = this.proc?.stdin;
+				if (wStdin?.writable === true) {
+					const wl0 = wStdin.writableLength;
+					let wret;
+					try {
+						wret = wStdin.write(startup);
+					} catch (error) {
+						trace("werr", {
+							s: this.opts.id,
+							commandId,
+							msg: error instanceof Error ? error.message : String(error)
+						});
+					}
+					if (wret !== void 0) {
+						trace("w1", {
+							s: this.opts.id,
+							commandId,
+							bytes: Buffer$1.byteLength(startup),
+							ret: wret,
+							wl0,
+							wl1: wStdin.writableLength,
+							payloadTail: traceRepr(startup.slice(-90), 120)
+						});
+						if (wret === false) wStdin.once("drain", () => {
+							trace("drain", {
+								s: this.opts.id,
+								commandId
+							});
+						});
+					}
+				} else trace("wskip", {
+					s: this.opts.id,
+					commandId
+				});
 				this.deathWaiters.push(deathWaiter);
 				if (dOpts.background === true) {
 					detach();
@@ -2340,9 +2623,39 @@ var PtySession = class {
 				interruptTimer = setTimeout(() => detach(), dOpts.timeoutSec === void 0 ? 12e4 : dOpts.timeoutSec * 1e3);
 			});
 		};
-		const run = this.queue.then(attempt, attempt);
-		this.queue = run.then(() => void 0, () => void 0);
-		return run;
+		return attempt();
+	}
+	/** §3.1（2026-10-25）interactive-stdin：向当前运行中的命令追加 stdin——只写既有通道
+	* 与身份，不新建命令、账本条目或输出游标；不重连、不重放（dead/disposed 明确拒绝）。
+	* 校验与写入全同步：多次 input 按调用顺序整段写入不交错；写入失败如实抛错（私有
+	* write() 的静默忽略不适用于回执语义）。stdin:"" 是零字节写入，不是 EOF。 */
+	input(options) {
+		const fail = (code, hint) => Promise.reject(/* @__PURE__ */ new Error(`${code} remote: ${hint}`));
+		if (this.state === "disposed") return fail("[E_SESSION_DISPOSED]", `pty session '${displayKey(this.opts.key)}' was disposed — input never reaches a disposed session`);
+		if (this.state === "dead") return fail("[E_SESSION_NOT_RUNNING]", `pty session '${displayKey(this.opts.key)}' died — input never reconnects or replays; start a new command (exec reconnects a fresh shell) and re-send only what is still needed`);
+		if (this.state === "starting") return fail("[E_SESSION_NOT_READY]", `pty session '${displayKey(this.opts.key)}' is still initializing — wait for the exec receipt, then input`);
+		const active = this.activeCommand;
+		if (active === null) return fail("[E_SESSION_NOT_RUNNING]", `pty session '${displayKey(this.opts.key)}' has no running command (state ${this.state}) — input writes into a command started by exec; it is never an implicit shell command`);
+		if (options.commandId !== void 0 && options.commandId !== active.commandId) return fail("[E_COMMAND_MISMATCH]", `commandId ${JSON.stringify(options.commandId)} does not match the running command ${active.commandId} — input aimed at an earlier prompt is never written to the next command`);
+		const stdin = this.proc?.stdin;
+		if (stdin?.writable !== true) return fail("[E_SESSION_WRITE_FAILED]", `pty session '${displayKey(this.opts.key)}' has no writable stdin channel (state ${this.state}) — follow the running command via job_output for its settled result`);
+		try {
+			stdin.write(options.stdin);
+			trace("in", {
+				s: this.opts.id,
+				commandId: active.commandId,
+				bytes: Buffer$1.byteLength(options.stdin, "utf8"),
+				repr: traceRepr(options.stdin, 60)
+			});
+		} catch (error) {
+			return fail("[E_SESSION_WRITE_FAILED]", `writing stdin to pty session '${displayKey(this.opts.key)}' failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return Promise.resolve({
+			session: displayKey(this.opts.key),
+			commandId: active.commandId,
+			...active.jobId !== void 0 ? { jobId: active.jobId } : {},
+			writtenBytes: Buffer$1.byteLength(options.stdin, "utf8")
+		});
 	}
 	/** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
 	dispose() {
@@ -2350,7 +2663,13 @@ var PtySession = class {
 		this.clearIdleTimer();
 		this.clearDeathTimer();
 		this.state = "disposed";
+		trace("dispose", {
+			s: this.opts.id,
+			key: this.opts.key
+		});
+		traceFlush();
 		this.startPromise = null;
+		this.detachedJob?.interrupt();
 		const proc = this.proc;
 		const close = this.procClose;
 		const group = this.reapGroup(proc?.pid, 1e3, close);
@@ -2361,7 +2680,7 @@ var PtySession = class {
 		]).then(() => {
 			if (this.proc === proc) this.proc = null;
 		});
-		this.write("exit\n");
+		if (this.detachedJob === null) this.write("exit\n");
 		this.opts.onDead?.();
 		return this.disposal;
 	}
@@ -2395,6 +2714,12 @@ var PtySession = class {
 			detached: true
 		});
 		this.proc = proc;
+		trace("start", {
+			s: this.opts.id,
+			key: this.opts.key,
+			argv: this.opts.argv,
+			pid: proc.pid
+		});
 		proc.stdout.setEncoding("utf8");
 		proc.stdout.on("data", (d) => {
 			this.onChunk?.(d);
@@ -2402,6 +2727,9 @@ var PtySession = class {
 		proc.stderr.setEncoding("utf8").on("data", (d) => {
 			this.diag = (this.diag + d).slice(-2e3);
 		});
+		proc.stdin.on("error", (err) => {
+			this.diag = (this.diag + `\n[remote: stdin write failed: ${err.message}]`).slice(-2e3);
+		});
 		this.procClose = new Promise((resolve$1) => {
 			proc.once("close", () => {
 				this.markDead();
@@ -2453,6 +2781,11 @@ var PtySession = class {
 			return;
 		}
 		this.state = "dead";
+		trace("dead", {
+			s: this.opts.id,
+			diagTail: this.diag.slice(-500)
+		});
+		traceFlush();
 		this.startPromise = null;
 		this.clearIdleTimer();
 		this.armDeathReaper();
@@ -2665,42 +2998,20 @@ function parseTargetForm(target) {
 			form: "hub",
 			machine: segs[0]
 		};
-		if (segs.length === 2 && segs[1] === "pty") return {
-			form: "hub-pty",
-			machine: segs[0]
-		};
-		throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — hub PTY takes no label (hub lane has no session id / parallelism this round)`);
+		if (segs.length > 1) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — hub takes a machine id (hub:<m4>); a hub machine's exec opens its default PTY, and handoff detaches it as pty:<id>`);
 	}
 	for (const transport of TRANSPORTS) {
 		if (!target.startsWith(`${transport}:`)) continue;
 		const rest = target.slice(transport.length + 1);
 		if (rest.length === 0) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — ${transport} takes a name`);
-		const ptyAt = rest.lastIndexOf(":pty");
-		if (ptyAt === -1) return {
+		if (/(^|:)pty(:|$)/.test(rest)) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — the :pty creation suffix is gone; a machine's exec opens its default PTY and handoff detaches it as pty:<id>`);
+		return {
 			form: "direct",
 			transport,
 			name: rest
 		};
-		const base = rest.slice(0, ptyAt);
-		if (base.length === 0) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — ":pty" needs a transport target before it ("ssh:pty" is the host named pty)`);
-		const tail = rest.slice(ptyAt + 4);
-		if (tail.startsWith(":")) {
-			if (tail.length === 1) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — empty label after ":pty:"`);
-			return {
-				form: "create-pty",
-				transport,
-				name: base,
-				label: tail.slice(1)
-			};
-		}
-		if (tail.length > 0) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — unexpected ${JSON.stringify(tail)} after ":pty"`);
-		return {
-			form: "create-pty",
-			transport,
-			name: base
-		};
 	}
-	if (target.includes(":")) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: unknown target ${JSON.stringify(target)} — transports are ssh: / docker: / incus: / hub:, the PTY selector is pty:<id|label>, creation appends :pty (roster lists names)`);
+	if (target.includes(":")) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: unknown target ${JSON.stringify(target)} — transports are ssh: / docker: / incus: / hub:, the PTY selector is pty:<id|label>; a machine's exec opens its default PTY and handoff detaches it (the old :pty creation suffix is gone)`);
 	return {
 		form: "bare",
 		name: target
@@ -2844,7 +3155,11 @@ async function probeTarget(plan, opts = {}) {
 	const runner = opts.runner ?? runOneShot;
 	const started = Date.now();
 	const r = await runner(plan.kind === "ssh" ? sshArgv(plan.connection ?? { host: plan.host }, {
-		extraArgs: ["-o", `ConnectTimeout=${ct}`],
+		extraArgs: [
+			...opts.muxArgvFor?.(plan) ?? [],
+			"-o",
+			`ConnectTimeout=${ct}`
+		],
 		command: "true"
 	}) : plan.kind === "docker" ? [
 		"docker",
@@ -2903,12 +3218,6 @@ function renderProbe(p) {
 		case "container": return `probe: container ${p.status} (just now, on demand)`;
 	}
 }
-/** session card（§5.5，`pty:<id|label>` 无 cmd）：connection/state/cwd/ttl 由调用方拼头行，这里渲染账本。 */
-function renderLedger(ledger) {
-	if (ledger.length === 0) return "ledger: empty — no command has run in this session yet";
-	const rows = [...ledger].reverse().map((e) => `  ${e.commandId}${e.jobId !== void 0 && e.jobId !== e.commandId ? ` (job ${e.jobId})` : ""} · ${e.running ? "running" : `exit ${e.exit}`}${e.running ? "" : ` · ${(e.durationMs / 1e3).toFixed(1)}s`} · ${e.summary}`);
-	return `ledger (last ${ledger.length}):\n${rows.join("\n")}`;
-}
 
 //#endregion
 //#region src/remote/ssh-config.ts
@@ -3059,7 +3368,7 @@ async function scanLocal(opts = {}) {
 	};
 }
 /** 统一池视图的 roster 呈现：机器三段 + BYO ssh 同位（built on）+ pty 会话段（caller-scoped）。 */
-function renderRoster(scan, entries, sessions, hubTargets) {
+function renderRoster(scan, entries, sessions, hubTargets, defaults) {
 	const lines = [];
 	if (hubTargets !== null) lines.push(`hub machines: ${hubTargets.map((t) => `hub:${t.id} (${t.label}${t.execEnabled ? "" : "; exec disabled"})`).join(", ") || "none"}`);
 	if (scan.ssh.error !== void 0) lines.push(`ssh hosts: no readable ~/.ssh/config (${scan.ssh.error})`);
@@ -3081,7 +3390,7 @@ function renderRoster(scan, entries, sessions, hubTargets) {
 		const id = s.identity;
 		const snap = s.snapshot;
 		const state = snap.busy ? "busy" : snap.state === "dead" ? "died" : `idle ${Math.round((snap.idleMs ?? 0) / 1e3)}s`;
-		return `pty:${id.id}${id.label !== void 0 ? ` (label ${id.label})` : ""} ${id.connection}${id.byo ? " (byo-pty)" : ""} [${state}]`;
+		return `pty:${id.id}${id.label !== void 0 ? ` (label ${id.label})` : ""} ${id.connection}${id.byo ? " (byo-pty)" : ""} [${state}${defaults?.get(id.id) !== void 0 ? `; default on ${defaults.get(id.id)}` : ""}]`;
 	}).join(" · ")}` : "pty sessions: none");
 	return lines.join("\n");
 }
@@ -3091,12 +3400,28 @@ function renderRoster(scan, entries, sessions, hubTargets) {
 /** R1：idle TTL 15 min——idle 随活动重置，在用会话永不超时（PtySession 双条件）。 */
 const REMOTE_PTY_IDLE_TTL_SEC = 900;
 /** P3（user 2026-10-19）：每 agent 10 个 PTY 会话，跨所有 connection 统一计；仅 error message 披露。 */
-const REMOTE_PTY_SESSION_LIMIT = 10;
+/** 二/三轮裁决（2026-11-01）：每 Agent session 全局 30 个 active PTY（默认/handoff/BYO 全计入）；
+* 仅触达上限时的错误回执与 roster 可见性披露，任何模型可见 surface 不预先公布。 */
+const REMOTE_PTY_SESSION_LIMIT = 30;
+/** hub 线 one-shot 监督披露（0.3.2-c）：对端 = 我们自己的 hub server（bash -lc 于独立进程组，
+*  Node 原生 TERM→2s→KILL + 输出环 + 租约生命周期）；superd-run helper 是 dumb-pipe 专用物，
+*  从不经 hub 上传（non-goal，docs/10_plans/2026-10-25-hub-remote-parity.md §3 O1/O8）。 */
+const HUB_RUNNER = "hub-lease (peer bash -lc, peer Node supervision)";
+/** hub PTY 泵资产：pump 与本模块同目录（npm 包与 Super 闭包同构，helper.ts 同款纪律）。
+*  ws 模块路径由 transport 侧（superd-hub 上下文，分叉的 proven 解析链）解析后经
+*  ptyEndpoint 传入——闭包自身子树无可解析的 ws，按名解析不在闭包里做（0.3.2-c 定稿）。 */
+function hubPtyAssets() {
+	return { pumpPath: join(dirname(fileURLToPath(import.meta.url)), "hub-pty-pump.mjs") };
+}
 /** 账本键与 jobId 同构（同格式 `<kind>-<16hex>`）；background 通道预传入 registry id 时两者字面相等。 */
 const genCommandId = () => `remote-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
 /** 双轨调度器：参数校验 → 目标语法（parseTargetForm）→ 统一 label 池 → oneshot 子进程 / pty 会话池。 */
 var RemoteDriver = class {
 	pool;
+	/** 默认 PTY 槽（spec remote-default-pty §1）：sessionKey → 归一 machineKey → pool key。
+	* 会话本体是普通 PtySession（id 创建即认领，roster 全可见）；槽登记在 dispose/TTL 后悬空，
+	* 取槽时经 pool.get（disposed 视同出池）惰性清理。 */
+	defaultSlots = /* @__PURE__ */ new Map();
 	labels = new LabelPool();
 	hubOwner = randomUUID();
 	hubProviders = /* @__PURE__ */ new Set();
@@ -3109,8 +3434,10 @@ var RemoteDriver = class {
 	runnerOf = /* @__PURE__ */ new WeakMap();
 	disposal;
 	ptyIdleTtlSec;
+	mux;
 	constructor(opts = {}) {
 		this.opts = opts;
+		this.mux = opts.sshMux ?? new SshMux();
 		this.ptyIdleTtlSec = opts.idleTtlSec ?? REMOTE_PTY_IDLE_TTL_SEC;
 		this.pool = new PtyPool({ idleTtlSec: this.ptyIdleTtlSec });
 	}
@@ -3149,38 +3476,24 @@ var RemoteDriver = class {
 		const hasSsh = params.ssh !== void 0;
 		if (hasSpawn && hasSsh) throw new Error("[E_PARAMS] remote: spawn and ssh are two different BYO entry points — pass one, not both");
 		const ptyForm = form.form === "pty-selector" || form.form === "empty" || form.form === "bare";
-		const sshForm = form.form === "ssh-prefix" || form.form === "empty" || form.form === "bare" || form.form === "direct" && form.transport === "ssh" || form.form === "create-pty" && form.transport === "ssh";
+		const sshForm = form.form === "ssh-prefix" || form.form === "empty" || form.form === "bare" || form.form === "direct" && form.transport === "ssh";
 		if (hasSpawn && !ptyForm) throw new Error("[E_PARAMS] remote: spawn pairs only with a pty target (pty, pty:<label>, or a bare label) — machines are dialed, not spawned");
-		if (hasSsh && !sshForm) throw new Error("[E_PARAMS] remote: ssh registration pairs with ssh-form targets only (ssh, ssh:<label>, ssh:<label>:pty, a bare label, or no target)");
+		if (hasSsh && !sshForm) throw new Error("[E_PARAMS] remote: ssh registration pairs with ssh-form targets only (ssh, ssh:<label>, a bare label, or no target)");
 	}
 	async execute(params, form, callCtx) {
 		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
-		const cap = this.opts.maxOutputChars ?? 3e4;
 		const sessionKey = callCtx.sessionKey ?? "no-session";
 		const hasCmd = params.cmd !== void 0 && params.cmd.length > 0;
-		params.spawn !== void 0 && params.spawn.length;
-		if (form.form === "hub" || form.form === "hub-pty") {
+		const hasSpawn = params.spawn !== void 0 && params.spawn.length > 0;
+		const bareHitsPty = form.form === "bare" && this.labels.resolve(form.name, sessionKey)?.kind === "pty";
+		if ((form.form === "direct" || form.form === "hub" || form.form === "bare" && !bareHitsPty) && params.mode !== "oneshot" && params.ssh === void 0 && !hasSpawn) {
+			const { session } = await this.defaultSlot(form, sessionKey);
+			if (!hasCmd) return this.cardReceipt(session);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
+		}
+		if (form.form === "hub") {
 			const hub = this.requireHub();
 			this.hubProviders.add(hub);
-			if (form.form === "hub-pty") {
-				if (!hasCmd) throw new Error("[E_PARAMS] remote: hub PTY takes cmd");
-				const result$1 = await hub.pty(form.machine, params.cmd, this.hubOwner, {
-					stdin: params.stdin,
-					timeout: timeoutSec
-				});
-				const out$1 = tailWindow(result$1.stdout, cap, result$1.outputStats?.stdout);
-				return {
-					...result$1,
-					target: `hub:${form.machine}`,
-					connection: `hub:${form.machine}`,
-					stdout: `[hub:${form.machine} pty — no session id, no parallel, no background]\n${out$1.text}`,
-					...out$1.stats ? { outputStats: {
-						...result$1.outputStats,
-						stdout: out$1.stats
-					} } : {},
-					...out$1.truncated === void 0 ? {} : { truncated: out$1.truncated }
-				};
-			}
 			const process$1 = this.own(await hub.start(form.machine, {
 				...params,
 				target: `hub:${form.machine}`,
@@ -3190,8 +3503,8 @@ var RemoteDriver = class {
 			if (this.disposed) process$1.cancel("owner disposed");
 			const result = await process$1.done;
 			const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
-			const out = tailWindow(stdout.text, cap, stdout.stats);
-			const err = tailWindow(stderr.text, cap, stderr.stats);
+			const out = disclose(stdout.text, stdout.stats);
+			const err = disclose(stderr.text, stderr.stats);
 			return {
 				...result,
 				mode: "oneshot",
@@ -3199,6 +3512,7 @@ var RemoteDriver = class {
 				connection: `hub:${form.machine}`,
 				cwd: null,
 				reconnected: false,
+				runner: HUB_RUNNER,
 				stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out.text,
 				stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
 				...out.stats ? { outputStats: {
@@ -3215,7 +3529,7 @@ var RemoteDriver = class {
 				await session.warm();
 				return this.warmReceipt(session);
 			}
-			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
 		}
 		if (params.ssh !== void 0) {
 			const label = form.form === "direct" || form.form === "bare" ? form.name : void 0;
@@ -3236,28 +3550,28 @@ var RemoteDriver = class {
 				kind: "ssh",
 				host: normalizeSshConnection(params.ssh).host,
 				connection: normalizeSshConnection(params.ssh)
-			}, `ssh:${name$1}`, params, timeoutSec, cap);
+			}, `ssh:${name$1}`, params, timeoutSec);
 		}
 		if (form.form === "pty-selector" && form.idOrLabel === void 0) throw new Error("[E_PARAMS] remote: \"pty\" alone selects nothing — append an id/label (pty:pty-1a2b, pty:build) or pass spawn to create one");
 		if (form.form === "pty-selector") {
 			const session = this.resolvePty(form.idOrLabel, sessionKey);
 			if (!hasCmd) return this.cardReceipt(session);
-			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
 		}
 		if (form.form === "direct") {
 			const plan$1 = form.transport === "ssh" ? this.sshPlanFor(form.name, sessionKey) : resolveTarget(`${form.transport}:${form.name}`);
-			return await this.oneshot(plan$1, `${form.transport}:${form.name}`, params, timeoutSec, cap);
+			return await this.oneshot(plan$1, `${form.transport}:${form.name}`, params, timeoutSec);
 		}
 		if (form.form !== "bare") throw new Error("[E_INTERNAL] remote: unreachable target form after routing");
 		const entry = await this.resolvePoolEntry(form.name, sessionKey);
 		if (entry.kind === "pty") {
 			const session = this.resolvePty(form.name, sessionKey);
 			if (!hasCmd) return this.cardReceipt(session);
-			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
 		}
-		if (entry.kind === "hub") return await this.hubOneshot(entry.machine, `hub:${entry.machine}`, params, timeoutSec, cap);
+		if (entry.kind === "hub") return await this.hubOneshot(entry.machine, `hub:${entry.machine}`, params, timeoutSec);
 		const plan = this.planOf(entry);
-		return await this.oneshot(plan, form.name, params, timeoutSec, cap);
+		return await this.oneshot(plan, form.name, params, timeoutSec);
 	}
 	/** Native-first copy routing (spec: remote-native-shortcut) — unchanged by the workbench round. */
 	copy(request, signal, callCtx = {}) {
@@ -3373,7 +3687,7 @@ var RemoteDriver = class {
 				const parsed = parseFileEndpoint(value);
 				if (!parsed.target) return { path: parsed.path };
 				const form = parseTargetForm(parsed.target);
-				if (form.form === "hub" || form.form === "hub-pty" || form.form === "pty-selector") throw new Error("rsync supports SSH endpoints only (plus one local endpoint); no mixed-transport or copy fallback");
+				if (form.form === "hub" || form.form === "pty-selector") throw new Error("rsync supports SSH endpoints only (plus one local endpoint); no mixed-transport or copy fallback");
 				const plan = await this.resolveConnectionTarget(parsed.target, callCtx);
 				this.assertOpen();
 				combined.throwIfAborted();
@@ -3415,49 +3729,68 @@ var RemoteDriver = class {
 			const plan = form.transport === "ssh" ? this.sshPlanFor(form.name, callCtx.sessionKey ?? "no-session") : resolveTarget(`${form.transport}:${form.name}`);
 			this.assertOpen();
 			signal.throwIfAborted();
-			process$1 = await this.nativeProcess(plan, params, params.timeout, signal);
+			process$1 = await this.nativeProcess(plan, `${form.transport}:${form.name}`, params, params.timeout, signal);
 		} else if (form.form === "bare") {
 			const entry = await this.resolvePoolEntry(form.name, callCtx.sessionKey ?? "no-session");
 			this.assertOpen();
 			signal.throwIfAborted();
 			if (entry.kind === "pty" || entry.kind === "hub") throw new Error("remote: background requires an ssh/docker/incus target");
-			process$1 = await this.nativeProcess(this.planOf(entry), params, params.timeout, signal);
+			process$1 = await this.nativeProcess(this.planOf(entry), form.name, params, params.timeout, signal);
 		} else throw new Error("remote: background oneshot takes a machine target");
 		this.own(process$1);
 		if (signal.aborted || this.disposed) process$1.cancel("owner closed during start");
 		return process$1;
 	}
-	async nativeProcess(plan, params, timeoutSec, signal = this.fileAbort.signal) {
+	async nativeProcess(plan, display, params, timeoutSec, signal = this.fileAbort.signal) {
+		const muxArgv = this.muxArgvFor(plan, display);
 		const cleanupTag = randomUUID().slice(0, 8);
-		const helper = await this.ensureHelper(plan);
+		const helper = await this.ensureHelper(plan, muxArgv);
 		if (helper !== null && !this.disposed) {
+			let killed$1 = false;
+			const kill$1 = () => {
+				if (killed$1) return;
+				killed$1 = true;
+				startOneShot(buildHelperKillgroupArgv(plan, helper.binPath, cleanupTag, muxArgv), { timeoutSec: 15 }).done.catch(() => {});
+			};
 			const process$2 = startOneShot(buildHelperOneShotArgv(plan, helper.binPath, {
 				tag: cleanupTag,
-				cmd: params.cmd
+				cmd: params.cmd,
+				...muxArgv !== void 0 ? { muxArgv } : {}
 			}), {
 				stdin: params.stdin,
-				timeoutSec
+				timeoutSec,
+				onCancel: kill$1
 			});
 			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(() => {});
+				kill$1();
 			}).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 }), {
+		let killed = false;
+		const kill = () => {
+			if (killed) return;
+			killed = true;
+			const pidfile = `"\${TMPDIR:-/tmp}/superd-oneshot-${cleanupTag}.pgid"`;
+			const cleanup = `p=$(cat ${pidfile} 2>/dev/null) && { kill -TERM -- "-$p" 2>/dev/null; sleep 0.3; kill -KILL -- "-$p" 2>/dev/null; }; rm -f ${pidfile}`;
+			startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, cleanup, { ...muxArgv !== void 0 ? { muxArgv } : {} }), { timeoutSec: 15 }).done.catch(() => {});
+		};
+		const process$1 = startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, params.cmd, {
+			cleanupTag,
+			...muxArgv !== void 0 ? { muxArgv } : {}
+		}), {
 			stdin: params.stdin,
-			timeoutSec
+			timeoutSec,
+			onCancel: kill
 		});
 		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"`;
-			const cleanup = `p=$(cat ${pidfile} 2>/dev/null) && { kill -TERM -- "-$p" 2>/dev/null; sleep 0.3; kill -KILL -- "-$p" 2>/dev/null; }; rm -f ${pidfile}`;
-			startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, cleanup, {}), { timeoutSec: 15 }).done.catch(() => {});
+			kill();
 		}).catch(() => {});
 		const work = Promise.resolve(process$1);
 		this.starting.add(work);
@@ -3466,14 +3799,14 @@ var RemoteDriver = class {
 	}
 	/** 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) {
+	async ensureHelper(plan, muxArgv) {
 		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);
+			return await this.helpers.ensure(plan, muxArgv ?? []);
 		} catch {
 			return null;
 		}
@@ -3586,6 +3919,16 @@ var RemoteDriver = class {
 			host: name$1
 		};
 	}
+	/** Task E MUX 身份：仅 SSH plan 注入（docker/incus/hub 返回 undefined）。身份键 = 原始
+	* target 串 + 有效连接字段（host/user/port/key/ProxyJump）——同身份共享 master，跨身份
+	* 不串 socket；目录/寿命/拆除全部由 SshMux 自持。 */
+	muxArgvFor(plan, target) {
+		if (plan.kind !== "ssh") return void 0;
+		return this.mux.argvFor({
+			target,
+			connection: plan.connection ?? { host: plan.host }
+		});
+	}
 	/** BYO ssh 注册（v2：无 spec 对比——label 占用即拒；注册成功才认领）。返回实际名（label 或 s-id）。 */
 	registerByoSsh(label, connection, sessionKey) {
 		this.assertOpen();
@@ -3615,7 +3958,8 @@ var RemoteDriver = class {
 		const live = this.pool.list().filter(({ key: key$1 }) => key$1.startsWith(`${sessionKey}|`)).map(({ key: key$1 }) => this.pool.get(key$1)).filter((s) => s !== void 0 && s.sessionState !== "dead");
 		if (live.length >= REMOTE_PTY_SESSION_LIMIT) {
 			const listing = live.map(sessionLine).join(" · ");
-			throw new Error(`[E_SESSION_LIMIT] remote: this Agent already holds ${live.length} live PTY sessions (limit ${REMOTE_PTY_SESSION_LIMIT}) — close one ({action:"close", target:"pty:<id>"}); idle sessions are reaped after ${this.ttlMinutes()} min.\n  live: ${listing}`);
+			throw new Error(`[E_SESSION_LIMIT] remote: this Agent already holds ${live.length} live PTY sessions — the per-Agent session global limit (${REMOTE_PTY_SESSION_LIMIT}) is reached. Check the live sessions below (or {action:"status"} for the roster), then close one ({action:"close", target:"pty:<id>" or the machine name}), kill its running job (job_kill), reuse a session, or run {mode:"oneshot"} instead.
+  live: ${listing}`);
 		}
 		const { label } = opts;
 		if (label !== void 0) validateLabel(label);
@@ -3664,7 +4008,7 @@ var RemoteDriver = class {
 	isBuiltOn(connection, sessionKey) {
 		return connection.startsWith("ssh:") && this.labels.resolve(connection.slice(4), sessionKey)?.kind === "ssh-byo";
 	}
-	/** PTY 创建形唯一实现（execute 与 background 预建共用）：spawn BYO / ssh BYO / native `<transport>:pty`。 */
+	/** PTY 创建形唯一实现（execute 与 background 预建共用）：spawn BYO（spec 2026-11-01：native `:pty`/hub-pty 创建语法已删，machine 会话经默认槽 + handoff）。 */
 	createPtyLane(params, form, sessionKey) {
 		if (params.spawn !== void 0 && params.spawn.length > 0) {
 			const label = form.form === "pty-selector" && form.idOrLabel !== void 0 ? form.idOrLabel : form.form === "bare" ? form.name : void 0;
@@ -3677,30 +4021,246 @@ var RemoteDriver = class {
 				origin: params.spawn
 			}, sessionKey) };
 		}
-		if (params.ssh !== void 0 && form.form === "create-pty") {
-			const name$1 = this.registerByoSsh(form.name, params.ssh, sessionKey);
-			const connection = normalizeSshConnection(params.ssh);
-			const plan = {
-				kind: "ssh",
-				host: connection.host,
-				connection
+	}
+	/** 池条目的槽键归一：同一实体（host/container/machine 身份）跨裸名/前缀/撞名前缀共享同一默认槽。 */
+	machineKeyOfEntry(entry) {
+		switch (entry.kind) {
+			case "ssh": return `ssh:${entry.host}`;
+			case "ssh-byo": return `byo:${entry.name}`;
+			case "docker": return `docker:${entry.container}`;
+			case "incus": return `incus:${entry.container}`;
+			case "hub": return `hub:${entry.machine}`;
+			case "pty": throw new Error("remote: a PTY session is not a machine slot");
+		}
+	}
+	/** 默认槽的 machine 规格：归一 key + 创建 argv + 展示 connection（hub 每次经 ptyEndpoint 重验 pairing，P10）。 */
+	async machineSlotSpec(form, sessionKey) {
+		if (form.form === "hub") {
+			const hub = this.requireHub();
+			this.hubProviders.add(hub);
+			const endpoint = hub.ptyEndpoint(form.machine);
+			return {
+				key: `hub:${form.machine}`,
+				argv: this.opts.hubPtyArgvFor !== void 0 ? this.opts.hubPtyArgvFor(endpoint) : buildHubPtyArgv(endpoint, hubPtyAssets()),
+				connection: `hub:${form.machine}`
 			};
-			return { session: this.createSession({
+		}
+		if (form.form === "direct") {
+			if (form.transport === "ssh") {
+				const entry = this.labels.resolve(form.name, sessionKey);
+				if (entry?.kind === "ssh-byo") {
+					const connection = entry.connection;
+					return {
+						key: `byo:${entry.name}`,
+						argv: (this.opts.ptyArgvFor ?? buildPtyArgv)({
+							kind: "ssh",
+							host: connection.host,
+							connection
+						}),
+						connection: `ssh:${entry.name}`,
+						builtOn: true
+					};
+				}
+				return {
+					key: `ssh:${form.name}`,
+					argv: (this.opts.ptyArgvFor ?? buildPtyArgv)({
+						kind: "ssh",
+						host: form.name
+					}),
+					connection: `ssh:${form.name}`
+				};
+			}
+			const plan = resolveTarget(`${form.transport}:${form.name}`);
+			return {
+				key: `${form.transport}:${form.name}`,
 				argv: (this.opts.ptyArgvFor ?? buildPtyArgv)(plan),
-				connection: `ssh:${name$1}`,
-				byo: false,
-				...form.label !== void 0 ? { label: form.label } : {}
-			}, sessionKey) };
+				connection: `${form.transport}:${form.name}`
+			};
 		}
-		if (form.form === "create-pty") {
-			const plan = form.transport === "ssh" ? this.sshPlanFor(form.name, sessionKey) : resolveTarget(`${form.transport}:${form.name}`);
-			return { session: this.createSession({
+		if (form.form === "bare") {
+			const entry = await this.resolvePoolEntry(form.name, sessionKey);
+			this.assertOpen();
+			if (entry.kind === "hub") return this.machineSlotSpec({
+				form: "hub",
+				machine: entry.machine
+			}, sessionKey);
+			if (entry.kind === "pty") throw new Error("[E_INTERNAL] remote: bare pty entries route before machine slots");
+			const key = this.machineKeyOfEntry(entry);
+			if (entry.kind === "ssh") return {
+				key,
+				argv: (this.opts.ptyArgvFor ?? buildPtyArgv)({
+					kind: "ssh",
+					host: entry.host
+				}),
+				connection: `ssh:${entry.name}`
+			};
+			if (entry.kind === "ssh-byo") return {
+				key,
+				argv: (this.opts.ptyArgvFor ?? buildPtyArgv)({
+					kind: "ssh",
+					host: entry.connection.host,
+					connection: entry.connection
+				}),
+				connection: `ssh:${entry.name}`,
+				builtOn: true
+			};
+			const plan = entry.kind === "docker" ? resolveTarget(`docker:${entry.container}`) : resolveTarget(`incus:${entry.container}`);
+			return {
+				key,
 				argv: (this.opts.ptyArgvFor ?? buildPtyArgv)(plan),
-				connection: `${form.transport}:${form.name}`,
+				connection: `${entry.kind === "docker" ? "docker" : "incus"}:${entry.name}`
+			};
+		}
+		throw new Error(`[E_TARGET_FORMAT] remote: a machine target is required (ssh:<name>, docker:<name>, incus:<name>, hub:<m4>, or a bare pool name) — got form ${JSON.stringify(form.form)}`);
+	}
+	/** 取/懒建 machine 的默认 PTY 槽：dead/disposed 槽惰性重建；id 创建即认领（roster 全可见 + 防撞）。 */
+	async defaultSlot(form, sessionKey) {
+		const spec = await this.machineSlotSpec(form, sessionKey);
+		this.assertOpen();
+		const byKey = this.defaultSlots.get(sessionKey) ?? /* @__PURE__ */ new Map();
+		this.defaultSlots.set(sessionKey, byKey);
+		const existingKey = byKey.get(spec.key);
+		if (existingKey !== void 0) {
+			const existing = this.pool.get(existingKey);
+			if (existing !== void 0) return {
+				session: existing,
+				machineKey: spec.key,
+				isNew: false
+			};
+			byKey.delete(spec.key);
+		}
+		const session = this.createSession({
+			argv: spec.argv,
+			connection: spec.connection,
+			byo: false,
+			...spec.builtOn === true ? { builtOn: true } : {}
+		}, sessionKey);
+		byKey.set(spec.key, session.key);
+		return {
+			session,
+			machineKey: spec.key,
+			isNew: true
+		};
+	}
+	releaseDefaultSlot(machineKey, sessionKey) {
+		this.defaultSlots.get(sessionKey)?.delete(machineKey);
+	}
+	/** 按池键反查并解绑默认槽（background 提交即 handoff 用）；非槽会话无操作。 */
+	releaseSlotByPoolKey(poolKey, sessionKey) {
+		const byKey = this.defaultSlots.get(sessionKey);
+		if (byKey === void 0) return;
+		for (const [machineKey, key] of byKey) if (key === poolKey) {
+			byKey.delete(machineKey);
+			return;
+		}
+	}
+	/** roster/status 面：本 session 的默认槽标注（session id → machineKey；悬空条目过滤）。 */
+	defaultMarks(sessionKey) {
+		const marks = /* @__PURE__ */ new Map();
+		const byKey = this.defaultSlots.get(sessionKey);
+		if (byKey === void 0) return marks;
+		for (const [machineKey, poolKey] of byKey) {
+			const s = this.pool.get(poolKey);
+			if (s !== void 0) marks.set(s.identity.id, machineKey);
+		}
+		return marks;
+	}
+	/** spec §1 handoff（2026-11-01 二/三轮裁决）：把 machine 默认 PTY 解绑成可寻址 pty:<id>——同引用移动
+	* （不重启、不复制输出流）；fresh（尚无默认槽）= 后台创建空闲 shell 再隔离（默认 PTY 思维模型恒
+	* ready，创建时机是实现细节）；busy = 附当前命令与 job 句柄。machine 下次 exec 按需新建默认 PTY。 */
+	async handoff(target, callCtx = {}) {
+		this.assertOpen();
+		const sessionKey = callCtx.sessionKey ?? "no-session";
+		const form = parseTargetForm(target);
+		if (form.form !== "direct" && form.form !== "bare" && form.form !== "hub") throw new Error(`[E_TARGET_FORMAT] remote: handoff detaches a machine's default PTY — pass a machine target (ssh:dev4, docker:c, hub:<m4>, or a bare pool name); addressable sessions are already detached, and ${JSON.stringify(target)} is not a machine`);
+		const spec = await this.machineSlotSpec(form, sessionKey);
+		this.assertOpen();
+		let session;
+		const poolKey = this.defaultSlots.get(sessionKey)?.get(spec.key);
+		if (poolKey !== void 0) session = this.pool.get(poolKey);
+		let created = false;
+		if (session === void 0) {
+			this.releaseDefaultSlot(spec.key, sessionKey);
+			session = this.createSession({
+				argv: spec.argv,
+				connection: spec.connection,
 				byo: false,
-				...form.label !== void 0 ? { label: form.label } : {}
-			}, sessionKey) };
+				...spec.builtOn === true ? { builtOn: true } : {}
+			}, sessionKey);
+			created = true;
+			await session.warm();
 		}
+		this.releaseDefaultSlot(spec.key, sessionKey);
+		const id = session.identity;
+		const snap = session.snapshot;
+		const activeCmd = session.active;
+		const lines = [
+			`handed off pty:${id.id}${id.label !== void 0 ? ` (label ${id.label})` : ""} — ${id.connection}${id.builtOn ? " (built on)" : ""}`,
+			created ? "fresh idle shell created and detached" : snap.state === "dead" ? "session died — its next dispatch reconnects a fresh shell" : "detached",
+			`this machine's next exec opens a fresh default PTY`
+		];
+		if (activeCmd !== null) lines.push(`still running: command ${activeCmd.commandId}${activeCmd.jobId !== void 0 ? ` — follow with job_output ${activeCmd.jobId}, cancel with job_kill` : " — a synchronous exec settles into its receipt; a timeout handoff is adoptable via job_output"}`);
+		return {
+			mode: "pty",
+			target: `pty:${id.id}`,
+			session: `pty:${id.id}`,
+			...id.label !== void 0 ? { label: id.label } : {},
+			connection: id.connection,
+			exit: null,
+			cwd: session.lastCwd,
+			timedOut: false,
+			reconnected: false,
+			stdout: lines.join("\n"),
+			durationMs: 0,
+			...created ? { created: true } : {},
+			...activeCmd !== null ? {
+				running: true,
+				commandId: activeCmd.commandId
+			} : {},
+			...this.ptyTtl(session.key)
+		};
+	}
+	/** close 统一入口（spec §1 + 三轮补充裁决）：machine target 只关默认槽；pty selector 关该会话；
+	* 不存在 job 定位——取消运行中命令的唯一入口是官方 job_kill。 */
+	async close(target, sessionKey, force = false) {
+		this.assertOpen();
+		const form = parseTargetForm(target);
+		const bareIsPty = form.form === "bare" && this.labels.resolve(form.name, sessionKey)?.kind === "pty";
+		if (form.form === "direct" || form.form === "hub" || form.form === "bare" && !bareIsPty) return this.closeDefault(form, sessionKey, force);
+		if (form.form === "pty-selector") {
+			if (form.idOrLabel === void 0) throw new Error("[E_PARAMS] remote: \"pty\" alone selects nothing — append an id/label (pty:pty-1a2b, pty:build)");
+			return this.closePty(form.idOrLabel, sessionKey, force);
+		}
+		if (form.form === "bare") return this.closePty(form.name, sessionKey, force);
+		throw new Error(`[E_TARGET_FORMAT] remote: close takes a machine target (closes its default PTY) or pty:<id|label> — got ${JSON.stringify(target)}`);
+	}
+	async closeDefault(form, sessionKey, force) {
+		const spec = await this.machineSlotSpec(form, sessionKey);
+		this.assertOpen();
+		const poolKey = this.defaultSlots.get(sessionKey)?.get(spec.key);
+		if (poolKey === void 0) return {
+			session: spec.key,
+			connection: spec.connection,
+			closed: false,
+			reason: "not-found",
+			killed: [],
+			message: `no default PTY on ${spec.key} — a machine's first exec opens one`
+		};
+		const session = this.pool.get(poolKey);
+		if (session === void 0) {
+			this.releaseDefaultSlot(spec.key, sessionKey);
+			return {
+				session: spec.key,
+				connection: spec.connection,
+				closed: false,
+				reason: "already-closed-or-reaped",
+				killed: [],
+				message: `the default PTY on ${spec.key} was already closed or reaped after ${this.ttlMinutes()} min idle`
+			};
+		}
+		const r = this.closePty(session.identity.id, sessionKey, force);
+		if (r.closed) this.releaseDefaultSlot(spec.key, sessionKey);
+		return r;
 	}
 	/** background PTY lane：会话先占位（不拨号）再进官方 jobs registry——首回执必须能寻址；
 	* registry 拒绝时把新建的会话拆掉（复用形的会话绝不拆）。返回 undefined = 走普通 oneshot job。 */
@@ -3712,9 +4272,9 @@ var RemoteDriver = class {
 		const form = parseTargetForm(prepared.target);
 		const target = (id$1) => ({
 			target: `pty:${id$1}`,
-			cmd: params.cmd,
-			stdin: params.stdin,
-			timeout: params.timeout,
+			cmd: prepared.cmd,
+			stdin: prepared.stdin,
+			timeout: prepared.timeout,
 			mode: "pty"
 		});
 		const lane = this.createPtyLane(prepared, form, sessionKey);
@@ -3729,6 +4289,20 @@ var RemoteDriver = class {
 				cleanup: () => void 0
 			};
 		}
+		if (lane === void 0 && (form.form === "direct" || form.form === "hub" || form.form === "bare" && this.labels.resolve(form.name, sessionKey)?.kind !== "pty") && prepared.mode !== "oneshot") {
+			const slot = await this.defaultSlot(form, sessionKey);
+			this.assertOpen();
+			const id$1 = slot.session.identity;
+			return {
+				input: target(id$1.id),
+				session: `pty:${id$1.id}`,
+				connection: id$1.connection,
+				...id$1.label !== void 0 ? { label: id$1.label } : {},
+				cleanup: () => {
+					if (slot.isNew) slot.session.dispose();
+				}
+			};
+		}
 		if (lane === void 0) return void 0;
 		const id = lane.session.identity;
 		return {
@@ -3788,15 +4362,53 @@ var RemoteDriver = class {
 			this.pool.get(key)?.attachJob(commandId, jobId);
 		}
 	}
-	async dispatchPty(session, params, callCtx, timeoutSec, cap) {
+	/** spec remote-default-pty §1（2026-11-01）：exec stdin-only 写入核心——向已有 live PTY 的当前运行命令
+	* 追加 exact-byte stdin。寻址：pty:<id|label> / 裸 label 命中 pty 项 / machine target（其默认槽的
+	* 当前命令，无槽不懒建、如实报错）。不触发拨号、创建或重连；回执附 connection/label 供工具层渲染。 */
+	async input(target, options, callCtx = {}) {
+		this.assertOpen();
+		const sessionKey = callCtx.sessionKey ?? "no-session";
+		const form = parseTargetForm(target);
+		let session;
+		if (form.form === "pty-selector") {
+			if (form.idOrLabel === void 0) throw new Error("[E_PARAMS] remote: \"pty\" alone selects nothing — append an id/label (pty:pty-1a2b, pty:build)");
+			session = this.resolvePty(form.idOrLabel, sessionKey);
+		} else if (form.form === "bare" && this.labels.resolve(form.name, sessionKey)?.kind === "pty") session = this.resolvePty(form.name, sessionKey);
+		else if (form.form === "direct" || form.form === "hub" || form.form === "bare") {
+			const spec = await this.machineSlotSpec(form, sessionKey);
+			this.assertOpen();
+			const poolKey = this.defaultSlots.get(sessionKey)?.get(spec.key);
+			const slot = poolKey !== void 0 ? this.pool.get(poolKey) : void 0;
+			if (slot === void 0) throw new Error(`[E_SESSION_NOT_RUNNING] remote: no default PTY on ${spec.key} yet — start a command first ({action:"exec", target:"${spec.key}", cmd:…}); a raw stdin write goes to the command running there`);
+			session = slot;
+		} else throw new Error(`[E_TARGET_FORMAT] remote: a raw stdin write goes into a live PTY session — pass pty:<id|label>, a bare session label, or a machine target (its default PTY); got ${JSON.stringify(target)}`);
+		const receipt = await session.input(options);
+		const id = session.identity;
+		return {
+			...receipt,
+			connection: id.connection,
+			...id.label !== void 0 ? { label: id.label } : {}
+		};
+	}
+	async dispatchPty(session, params, callCtx, timeoutSec) {
+		const hubConn = session.identity.connection;
+		if (hubConn.startsWith("hub:")) {
+			const hub = this.requireHub();
+			this.hubProviders.add(hub);
+			hub.ptyEndpoint(hubConn.slice(4));
+		}
 		const commandId = callCtx.commandId ?? genCommandId();
 		const r = await session.dispatch(params.cmd, {
 			stdin: params.stdin,
 			timeoutSec,
 			commandId,
-			...callCtx.ptyBackground === true ? { background: true } : {}
+			...callCtx.ptyBackground === true ? {
+				background: true,
+				jobId: commandId
+			} : {}
 		});
-		const out = tailWindow(r.output, cap, r.outputStats?.stdout);
+		if (callCtx.ptyBackground === true && r.running === true) this.releaseSlotByPoolKey(session.key, callCtx.sessionKey ?? "no-session");
+		const out = disclose(r.output, r.outputStats?.stdout);
 		const id = session.identity;
 		return {
 			mode: "pty",
@@ -3859,14 +4471,14 @@ var RemoteDriver = class {
 			cwd: session.lastCwd,
 			timedOut: false,
 			reconnected: false,
-			stdout: [head, renderLedger(session.ledgerSnapshot())].join("\n"),
+			stdout: [head, activeLine(session)].join("\n"),
 			durationMs: 0,
 			...this.ptyTtl(session.key)
 		};
 	}
-	async oneshot(plan, display, params, timeoutSec, cap) {
+	async oneshot(plan, display, params, timeoutSec) {
 		this.assertOpen();
-		const process$1 = this.own(await this.nativeProcess(plan, params, timeoutSec));
+		const process$1 = this.own(await this.nativeProcess(plan, display, params, timeoutSec));
 		if (this.disposed) process$1.cancel("owner disposed");
 		const result = await process$1.done;
 		const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
@@ -3879,8 +4491,8 @@ var RemoteDriver = class {
 				stderr: stderr.stats
 			}
 		};
-		const out = tailWindow(r.stdout, cap, r.outputStats?.stdout);
-		const err = r.stderr.length > 0 ? tailWindow(r.stderr, cap, r.outputStats?.stderr) : void 0;
+		const out = disclose(r.stdout, r.outputStats?.stdout);
+		const err = r.stderr.length > 0 ? disclose(r.stderr, r.outputStats?.stderr) : void 0;
 		return {
 			mode: "oneshot",
 			target: display,
@@ -3899,13 +4511,13 @@ var RemoteDriver = class {
 			...this.runnerOf.get(process$1) === void 0 ? {} : { runner: this.runnerOf.get(process$1) }
 		};
 	}
-	async hubOneshot(machine, display, params, timeoutSec, cap) {
+	async hubOneshot(machine, display, params, timeoutSec) {
 		const process$1 = this.own(await this.hubOneshotProcess(machine, params));
 		if (this.disposed) process$1.cancel("owner disposed");
 		const result = await process$1.done;
 		const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
-		const out = tailWindow(stdout.text, cap, stdout.stats);
-		const err = tailWindow(stderr.text, cap, stderr.stats);
+		const out = disclose(stdout.text, stdout.stats);
+		const err = disclose(stderr.text, stderr.stats);
 		return {
 			...result,
 			mode: "oneshot",
@@ -3913,6 +4525,7 @@ var RemoteDriver = class {
 			connection: display,
 			cwd: null,
 			reconnected: false,
+			runner: HUB_RUNNER,
 			stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out.text,
 			stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
 			...out.stats ? { outputStats: {
@@ -3951,17 +4564,20 @@ var RemoteDriver = class {
 			return s === void 0 ? null : s;
 		}).filter((s) => s !== null);
 		const hub = this.opts.getHub?.();
-		return renderRoster(scan, this.labels.list(callCtx.sessionKey ?? "no-session"), sessions, hub === void 0 ? null : hub.listTargets());
+		return renderRoster(scan, this.labels.list(callCtx.sessionKey ?? "no-session"), sessions, hub === void 0 ? null : hub.listTargets(), this.defaultMarks(callCtx.sessionKey ?? "no-session"));
 	}
 	/** status probe（target 无 cmd）：机器面 = probe + 该 connection 上的会话；pty selector = session card。 */
 	async status(target, callCtx = {}) {
 		this.assertOpen();
 		const sessionKey = callCtx.sessionKey ?? "no-session";
 		const form = parseTargetForm(target);
-		if (form.form === "hub" || form.form === "hub-pty") {
+		if (form.form === "hub") {
 			const row = this.requireHub().listTargets().find((t) => t.id === form.machine);
 			if (!row) throw new Error(`unknown remote machine ${form.machine} — select a remote machine from the Hub roster; local execution is not available`);
-			return `hub:${form.machine} — Hub remote machine (${row.label}); exec ${row.execEnabled ? "enabled" : "disabled"}; not probed`;
+			const hubSlotKey = `hub:${form.machine}`;
+			const hubSlotPoolKey = this.defaultSlots.get(sessionKey)?.get(hubSlotKey);
+			const hubSlot = hubSlotPoolKey !== void 0 ? this.pool.get(hubSlotPoolKey) : void 0;
+			return [`hub:${form.machine} — Hub remote machine (${row.label}); exec ${row.execEnabled ? "enabled" : "disabled"}; not probed`, hubSlot === void 0 ? `default PTY: none — this machine's first exec opens one` : `default PTY: ${sessionLine(hubSlot)}`].join("\n");
 		}
 		if (form.form === "pty-selector") {
 			if (form.idOrLabel === void 0) throw new Error("[E_PARAMS] remote: \"pty\" alone selects nothing — append an id/label (pty:pty-1a2b, pty:build)");
@@ -3979,15 +4595,23 @@ var RemoteDriver = class {
 		const plan = this.planOf(entry);
 		const head = `${target} — ${plan.kind === "ssh" ? "ssh host" : `${plan.kind} container`}${entry.kind === "ssh-byo" ? " (built on)" : ""}`;
 		const runner = this.opts.probeRunner ?? runOneShot;
-		const probe = await probeTarget(plan, { runner: (argv, options) => {
-			this.assertOpen();
-			return runner(argv, options);
-		} });
+		const probe = await probeTarget(plan, {
+			runner: (argv, options) => {
+				this.assertOpen();
+				return runner(argv, options);
+			},
+			muxArgvFor: (p) => this.muxArgvFor(p, target) ?? []
+		});
 		const prefix = `${sessionKey}|`;
 		const onConnection = this.pool.list().filter(({ key }) => key.startsWith(prefix)).map(({ key }) => this.pool.get(key)).filter((s) => s !== void 0 && s.identity.connection === `${plan.kind === "ssh" ? "ssh" : plan.kind}:${name$1}`);
+		const slotKey = this.machineKeyOfEntry(entry);
+		const slotPoolKey = this.defaultSlots.get(sessionKey)?.get(slotKey);
+		const slotSession = slotPoolKey !== void 0 ? this.pool.get(slotPoolKey) : void 0;
+		const slotLine = slotSession === void 0 ? `default PTY: none — this machine's first exec opens one` : `default PTY: ${sessionLine(slotSession)}`;
 		return [
 			head,
 			renderProbe(probe),
+			slotLine,
 			onConnection.length > 0 ? `pty sessions on this connection: ${onConnection.map(sessionLine).join(" · ")}` : "pty sessions on this connection: none"
 		].join("\n");
 	}
@@ -4002,8 +4626,7 @@ var RemoteDriver = class {
 		this.assertOpen();
 		const form = parseTargetForm(target);
 		if (form.form === "pty-selector") throw new Error("remote: a PTY session is not a filesystem connection");
-		if (form.form === "hub" || form.form === "hub-pty") throw new Error("remote: hub endpoints resolve through the Hub file lane, not a CLI connection");
-		if (form.form === "create-pty") throw new Error("remote: a PTY session is not a filesystem connection");
+		if (form.form === "hub") throw new Error("remote: hub endpoints resolve through the Hub file lane, not a CLI connection");
 		if (form.form === "direct") return form.transport === "ssh" ? this.sshPlanFor(form.name, callCtx.sessionKey ?? "no-session") : resolveTarget(`${form.transport}:${form.name}`);
 		if (form.form === "ssh-prefix" || form.form === "empty") throw new Error("[E_TARGET_FORMAT] remote: connection targets need a name");
 		const entry = await this.resolvePoolEntry(form.name, callCtx.sessionKey ?? "no-session");
@@ -4033,6 +4656,7 @@ var RemoteDriver = class {
 		if (this.disposal) return this.disposal;
 		this.disposed = true;
 		this.labels.clear();
+		this.defaultSlots.clear();
 		this.fileAbort.abort(/* @__PURE__ */ new Error("remote owner disposed"));
 		for (const process$1 of this.processes) process$1.cancel("remote owner disposed");
 		return this.disposal = (async () => {
@@ -4043,12 +4667,18 @@ var RemoteDriver = class {
 				...[...this.hubProviders].map((hub) => hub.releaseOwner(this.hubOwner))
 			]);
 			this.hubProviders.clear();
+			await this.mux.dispose();
 		})();
 	}
 };
 /** direct 形态回退到 resolveTarget 可解析的名字（ssh:dev4 → dev4）。 */
 function directName(form) {
-	return form.form === "direct" ? form.name : form.form === "create-pty" ? form.name : "";
+	return form.form === "direct" ? form.name : "";
+}
+/** session card 的当前命令行（spec 2026-11-01：历史 ledger 已删，只报活动命令）。 */
+function activeLine(s) {
+	const a = s.active;
+	return a === null ? "no command running" : `running: ${a.commandId}${a.jobId !== void 0 ? ` (job ${a.jobId})` : ""} — feed it stdin with exec stdin-only, follow job_output, cancel job_kill`;
 }
 /** roster/status 一行的会话描述：`p-ab12 (label build) ssh:dev4 idle 12s`。 */
 function sessionLine(s) {
@@ -4070,16 +4700,21 @@ const ptyOutputSources = (holder) => [{
 		lossy: false
 	}
 }];
-const ptyOutcome = (aborted, result) => ({
-	status: aborted ? "killed" : result.exit === null ? "failed" : "completed",
-	detail: aborted ? `interrupted: ${result.exit === null ? "session died" : `exit ${result.exit}`}` : result.exit === null ? "session died" : `exit code: ${result.exit}`
-});
+/** 0.3.2-d CF：timedOut=true 且 aborted=false = 会话侧主动收束（close force / 行回收走的
+* dispose→interrupt 两段路）——同为 killed；exit 到手用 exit，只剩会话死亡时写 session closed。 */
+const ptyOutcome = (aborted, result) => {
+	const interrupted = aborted || result.timedOut === true;
+	return {
+		status: interrupted ? "killed" : result.exit === null ? "failed" : "completed",
+		detail: interrupted ? `interrupted: ${result.exit === null ? aborted ? "session died" : "session closed" : `exit ${result.exit}`}` : result.exit === null ? "session died" : `exit code: ${result.exit}`
+	};
+};
 /** No preparation or discovery before the official registry's admission. */
 function startRemoteJob(registry, input, exec, driver) {
 	if (!exec.agent) throw new Error("remote: background jobs require a live Agent owner");
 	const form = parseTargetForm(input.target);
-	if (form.form === "pty-selector" || form.form === "create-pty" || form.form === "hub-pty" || input.spawn !== void 0 || input.mode === "pty") {
-		if (form.form === "hub-pty") throw new Error("remote: hub-machine PTY has no background lane; use a direct ssh/docker/incus target or a pty session");
+	const machineForm = form.form === "direct" || form.form === "bare" || form.form === "hub";
+	if (form.form === "pty-selector" || input.spawn !== void 0 || input.mode === "pty" || machineForm && input.mode !== "oneshot") {
 		const holder = {};
 		return registry.start({
 			kind: "remote",
@@ -4205,116 +4840,123 @@ function adoptRunningPtyJob(registry, exec, label, job) {
 
 //#endregion
 //#region src/remote/tool.ts
-const NO_SESSION_KEY = "remote:no-session";
+const NO_SESSION_KEY$1 = "remote:no-session";
 /**
-* The model-visible surface of the `remote` tool (workbench round, plan
-* 2026-10-19-pty-workbench). ONE template literal — no backticks, no "${".
+* The model-visible surface of the `remote` tool (0.3.2-d user-ruled restructure:
+* Actions / Targets / PTY / Oneshot / Examples — the PTY block is the user's verbatim
+* final draft; Examples receipts match renderValue byte-for-byte).
+* ONE template literal — no backticks, no "${".
+*
+* 语义目标（surface 就是产品）：动作是唯一的派发维度；PTY 四词定位——stateful oneshot /
+* interact-able stdin / managed output / persistent env——回执形状与 oneshot 相同、只增状态，
+* 运行中的命令可分步观察后再补输（input 动作）；多步与交互任务默认进 PTY。
 */
-const REMOTE_TOOL_DESCRIPTION = `Remote execution and file transfer over ssh / docker / incus, plus stateful PTY workbenches. Pick the call shape:
-  {}                                   → roster (local scan; refreshes the name pool: ssh aliases, BYO identities, docker/incus containers, hub machines, live pty sessions)
-  {target}                             → status probe: machine reachability + its pty sessions, or a session card (connection, cwd, ledger of the last 20 commands) for pty:<id|label>
-  {target, cmd}                        → run cmd — oneshot (stateless bash -lc) on any machine target
-  {target, scriptPath:"/abs"}         → LOCAL script over stdin to a fixed bash -s (oneshot only; no cmd/stdin/spawn mix)
-  {target:"ssh:dev4:pty[:label]", cmd?}    → create a PTY session on that machine and run cmd in it; no cmd = warm creation returning the id. Tab semantics: every creation call opens a NEW session — parallel is first-class (max 10 per Agent, ssh:dev4 and docker:corti alike).
-  {target:"pty:<id|label>", cmd}           → run cmd in a live session (cwd/env survive; the receipt carries session, connection, commandId, cwd, env delta, idle-left)
-  {spawn, target?:"pty[:<label>]"|"<label>"|"", cmd?}  → create a BYO pty from a spawn command (e.g. docker exec -it img bash; nested hops are dumb pipes). spawn present IS the BYO entry point; no target = auto id.
-  {ssh:{...}, target?:"ssh[:<label>]"|"<label>"|"", cmd?}  → register a BYO ssh identity (ssh present IS the entry point); the label then works everywhere ssh: aliases do (roster marks it "built on"); ssh:<label>:pty opens a session on it. key is an existing origin file, never inline material; nothing is persisted; a new Agent registers again.
-  {action:"close", target:"pty:<id|label>", force?}  → close a session. Idempotent (unknown id → closed:false). Default rejects while a job is running and names it (job_kill it first, or wait); force:true closes the tab and kills the group in one step.
-  {action:"copy"|"rsync", src, dst, argv?}  → file transfer (see the action/src/dst fields)
-Bare names address ONE unified pool (machines + identities + sessions — roster lists it; a machine losing its bare name to an earlier claim is shown prefixed docker-foo / incus-foo). Prefixes ssh: / docker: / incus: / hub: force a channel. Creation always claims a fresh name: a taken label answers [E_LABEL_IN_USE] — address it without creation params, or pick another (specs are never compared). PTY sessions idle out after 15 min (running commands exempt; reads do not reset the clock).
+const REMOTE_TOOL_DESCRIPTION = `Remote shell (SSH, Docker, Incus, Hub): 1 default interactive PTY per machine (retains cwd/env). \`mode:"oneshot"\` = isolated, stateless.
 
-oneshot: 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 receipt 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).
+Actions:
+- exec {target, cmd? | scriptPath?, stdin?, mode?:"pty"|"oneshot"="pty", timeout?, run_in_background?:boolean, commandId?:string}: run command / script / raw stdin write. Machine target = default PTY. PTY \`stdin\` alone = raw write into running command (optional \`commandId\` guard). \`run_in_background:true\` = async job, returns handle instantly, PTY handed off automatically.
+- handoff {target:<machine>}: detach machine's default PTY -> \`pty:<id>\`. Next exec spawns fresh default.
+- add {ssh:{...} | spawn:"<cmd>", target?}: register BYO identity/PTY. Returns label. Taken label answers \`[E_LABEL_IN_USE]\`.
+- status {target?}: roster pool (no target) or machine probe / session card.
+- close {target, force?:boolean}: close PTY shell. Machine target closes only default PTY. Running command blocks close unless \`force:true\`.
 
-PTY is the stateful superset of oneshot: every command returns synchronously with exit + cwd + an env delta (NAMES only — added/changed/removed; values never leave the endpoint; fetch a value yourself if you need it). A command that outlives its timeout is NOT killed — it hands off as a running job: poll job_output <commandId>, cancel with job_kill (Ctrl-C first; the session survives). run_in_background uses the same lane and its jobId IS the commandId. A busy session rejects new commands ([E_SESSION_BUSY] names the running id and the ways out: job_output / job_kill / another session or oneshot).
+Targets & Semantics:
+- Targets: \`ssh:<n>\`, \`docker:<n>\`, \`incus:<n>\`, \`hub:<m4>\`, \`pty:<id|label>\` (or bare label). Busy PTY rejects new cmds (use input/poll/cancel/handoff/oneshot).
+- PTY: Stream includes echo/stderr. \`envDelta\` lists var names (no values). Expires after 15m idle. Timeout (default 120s) = sync wait limit (command keeps running as job: \`job_output\` / \`job_kill\`).
+- Oneshot: Separate stdout/stderr, verbatim exit code, stateless. \`stdin\` = startup only. Cached \`superd-run\` runner preferred over POSIX shim.
+- Script: \`scriptPath\` = local absolute file read before dial, runs as single \`bash -c\` cmd (same size limit). In PTY, runs as child process (\`cd\`/\`export\` do not affect parent shell). Hub inline cmd limit: 4096 chars.
+- Stdin: oneshot = \`fd0 → pipe\`; PTY = \`fd0 → pty slave\`, line disciplines. Literal bytes (\`\\n\`, \`\\u0003\` = Ctrl-C, \`\\u0004\` = Ctrl-D). Retention: 4M chars/stream (Hub oneshot 4MiB).
 
-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 (pty: REPL-style right after the command line — only helps commands that read stdin there). timeout (seconds, default 120): oneshot interrupts then kills the whole group; pty hands off. Native transport errors pass through verbatim — self-correct from them.`;
+Examples:
+remote {"action":"exec","target":"ssh:dev4","cmd":"cd /srv/app && pwd"}
+remote {"action":"exec","target":"ssh:dev4","cmd":"make test","run_in_background":true}
+remote {"action":"handoff","target":"ssh:dev4"}
+remote {"action":"exec","target":"pty:pty-irsq","stdin":"yes\\n","commandId":"remote-47676dff2c6443e8"}
+remote {"action":"exec","target":"ssh:dev4","mode":"oneshot","cmd":"uname -a"}
+remote {"action":"add","spawn":"ssh -t pc ssh -t dev4","target":"pty:dev4via"}
+remote {"action":"exec","target":"pty:dev4via","cmd":"hostname"}
+remote {"action":"add","ssh":{"host":"10.0.0.8","user":"u1","port":22,"key":"~/.ssh/id_key4"},"target":"ssh:lab"}
+remote_transfer {"mode":"rsync","src":"ssh:lab:/var/log/app/","dst":"~/app-logs/","argv":["-a"]}`;
+/** action 是唯一派发维度：每个动词声明自己的字段集，超出即报错（不做在场推断、不留别名）。 */
+const ACTION_PARAMS = {
+	exec: new Set([
+		"action",
+		"target",
+		"cmd",
+		"stdin",
+		"scriptPath",
+		"timeout",
+		"run_in_background",
+		"mode",
+		"commandId"
+	]),
+	handoff: new Set(["action", "target"]),
+	add: new Set([
+		"action",
+		"target",
+		"ssh",
+		"spawn"
+	]),
+	status: new Set(["action", "target"]),
+	close: new Set([
+		"action",
+		"target",
+		"force"
+	])
+};
+const ACTION_HINT = {
+	exec: "exec takes target plus cmd (or scriptPath, or stdin alone as a raw write into the running command) and the execution options; ssh/spawn belong to add",
+	handoff: "handoff takes exactly one field besides action: target — the machine whose default PTY becomes pty:<id>",
+	add: "add takes exactly one of ssh or spawn, plus an optional target label",
+	status: "status takes only an optional target — omit it for the roster",
+	close: "close takes a target (machine = its default PTY, or pty:<id|label>) and optional force — never a job id; cancel jobs with job_kill"
+};
 async function remoteExecute(ENV, args, exec) {
-	if (args.action === "copy" || args.action === "rsync") {
-		if (!args.src || !args.dst) throw new Error(`${args.action} requires src and dst absolute endpoints`);
-		if ([
-			args.cmd,
-			args.scriptPath,
-			args.stdin,
-			args.spawn,
-			args.ssh,
-			args.target,
-			args.timeout,
-			args.run_in_background,
-			args.force
-		].some((value) => value !== void 0)) throw new Error(`${args.action} cannot be combined with execution/PTY/job arguments`);
-		const KNOWN_PARAMS = new Set([
-			"action",
-			"force",
-			"src",
-			"dst",
-			"argv",
-			"pullArgv",
-			"pushArgv",
-			"verify",
-			"mkdir",
-			"run_in_background",
-			"target",
-			"ssh",
-			"spawn",
-			"cmd",
-			"scriptPath",
-			"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; 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");
-			const start = Date.now();
-			const receipt$1 = await ENV.driver.rsync({
-				src: args.src,
-				dst: args.dst,
-				...args.argv === void 0 ? {} : { argv: args.argv }
-			}, exec.signal, { sessionKey: ENV.getSessionKey(exec) });
-			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: formatTransferLine("rsync", receipt$1, rsyncDuration),
-				receipt: receipt$1,
-				exit: receipt$1.exit,
-				durationMs: rsyncDuration
-			};
-		}
-		const copyStart = Date.now();
-		const receipt = await ENV.driver.copy({
-			src: args.src,
-			dst: args.dst,
-			...args.verify === void 0 ? {} : { verify: args.verify },
-			...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
-			...args.argv === void 0 ? {} : { argv: args.argv },
-			...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
-			...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
-		}, exec.signal, { sessionKey: ENV.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;
+	const action = args.action;
+	if (action === void 0) throw new Error("[E_PARAMS] remote: action is required — \"exec\" (run a command or raw stdin write), \"handoff\" (detach a machine default PTY), \"add\" (register a BYO endpoint), \"status\" (roster / probe / session card), \"close\" (close a PTY shell)");
+	const allowed = ACTION_PARAMS[action];
+	if (allowed === void 0) throw new Error(`[E_PARAMS] remote: unknown action ${JSON.stringify(String(action))} — one of exec / handoff / add / close / status`);
+	for (const key of Object.keys(args)) if (!allowed.has(key)) throw new Error(`[E_PARAMS] remote: "${key}" does not belong to action "${action}" — ${ACTION_HINT[action]}`);
+	const sessionKey = ENV.getSessionKey(exec);
+	const hasTarget = typeof args.target === "string" && args.target.length > 0;
+	const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
+	if (action === "status") {
+		if (!hasTarget) return {
+			kind: "roster",
+			text: await ENV.driver.roster({ sessionKey }),
+			exit: null,
+			durationMs: 0
+		};
+		return {
+			kind: "status",
+			text: await ENV.driver.status(args.target, { sessionKey }),
+			exit: null,
+			durationMs: 0
+		};
+	}
+	if (action === "handoff") {
+		if (!hasTarget) throw new Error("[E_PARAMS] remote: action \"handoff\" requires target — the machine whose default PTY becomes an addressable pty:<id> (ssh:dev4, docker:c, hub:<m4>, or a bare pool name)");
+		const r$1 = await ENV.driver.handoff(args.target, { sessionKey });
 		return {
-			kind: "copy",
-			text: formatTransferLine("copy", receipt, copyDuration),
-			receipt,
-			exit: exits.length > 0 ? 0 : null,
-			durationMs: copyDuration
+			kind: "handoff",
+			text: r$1.stdout,
+			exit: null,
+			durationMs: 0,
+			session: r$1.session,
+			connection: r$1.connection,
+			...r$1.label !== void 0 ? { label: r$1.label } : {},
+			...r$1.cwd !== null && r$1.cwd !== void 0 ? { cwd: r$1.cwd } : {},
+			...r$1.created === true ? { created: true } : {},
+			...r$1.running === true && r$1.commandId !== void 0 ? {
+				running: true,
+				commandId: r$1.commandId
+			} : {},
+			...r$1.ttlSec !== void 0 ? { ttlSec: r$1.ttlSec } : {}
 		};
 	}
-	if (args.action === "close") {
-		if (typeof args.target !== "string" || args.target.length === 0) throw new Error("close requires target pty:<id|label>");
-		if ([
-			args.cmd,
-			args.scriptPath,
-			args.stdin,
-			args.spawn,
-			args.ssh,
-			args.timeout,
-			args.run_in_background
-		].some((value) => value !== void 0)) throw new Error("[E_PARAMS] close cannot be combined with execution/PTY/job arguments");
-		const r$1 = ENV.driver.closePty(args.target.startsWith("pty:") ? args.target.slice(4) : args.target, ENV.getSessionKey(exec), args.force === true);
+	if (action === "close") {
+		if (!hasTarget) throw new Error("[E_PARAMS] close requires target — a machine (closes its default PTY) or pty:<id|label>");
+		const r$1 = await ENV.driver.close(args.target, sessionKey, args.force === true);
 		return {
 			kind: "close",
 			text: r$1.closed ? `closed ${r$1.session} (${r$1.connection})${r$1.killed.length > 0 ? ` — killed running job ${r$1.killed.join(", ")}` : ""}` : `${r$1.session}: not closed (${r$1.reason}) — ${r$1.message ?? "no live session"}`,
@@ -4326,44 +4968,72 @@ async function remoteExecute(ENV, args, exec) {
 			killed: r$1.killed
 		};
 	}
-	if ([
-		args.src,
-		args.dst,
-		args.argv,
-		args.pullArgv,
-		args.pushArgv,
-		args.verify,
-		args.mkdir,
-		args.force
-	].some((value) => value !== void 0)) throw new Error("file/force fields require an action (copy / rsync / close)");
-	const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
-	const hasTarget = typeof args.target === "string" && args.target.length > 0;
-	const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
-	if (args.spawn !== void 0 && !hasSpawn) throw new Error("[E_PARAMS] remote: spawn must be a non-empty command string");
-	if (args.scriptPath !== void 0 && (hasSpawn || /^pty:/.test(args.target ?? "") || /:pty/.test(args.target ?? ""))) throw new Error("[E_SCRIPT_PARAMS] remote: scriptPath is oneshot-only — PTY lanes take cmd");
+	if (action === "add") {
+		const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
+		if (args.spawn !== void 0 && !hasSpawn) throw new Error("[E_PARAMS] remote: add: spawn must be a non-empty command string");
+		if (args.ssh === void 0 && !hasSpawn) throw new Error("[E_PARAMS] remote: action \"add\" registers a BYO endpoint — pass ssh:{host,...} (identity) or spawn:\"<command>\" (PTY), exactly one");
+		if (args.ssh !== void 0 && hasSpawn) throw new Error("[E_PARAMS] remote: add: ssh and spawn are two different BYO entry points — pass one, not both");
+		const r$1 = await ENV.driver.call({
+			...hasTarget ? { target: args.target } : {},
+			...args.ssh === void 0 ? {} : { ssh: args.ssh },
+			...hasSpawn ? { spawn: args.spawn } : {},
+			cmd: ""
+		}, { sessionKey });
+		const v$1 = workbenchValue(r$1);
+		v$1.created = true;
+		if (!hasSpawn) v$1.notice = `registered — address it as ${r$1.session ?? r$1.target} from now on (the label, id and ssh alias all work)`;
+		return v$1;
+	}
+	if (!hasTarget) throw new Error("[E_PARAMS] remote: action \"exec\" requires target — a machine (ssh:dev4, docker:corti, hub:<m4>, a pool name) or a PTY session (pty:<id|label>, a bare label, or <machine>:pty[:label] to create one). Status probes and the roster live under action \"status\".");
+	const target = args.target;
+	if (args.commandId !== void 0 && args.commandId.length === 0) throw new Error("[E_PARAMS] remote: commandId, when given, must be the non-empty id from the exec receipt / job_output");
+	if (args.scriptPath !== void 0) {
+		if (args.scriptPath.length === 0) throw new Error("[E_PARAMS] remote: scriptPath must be a non-empty absolute path");
+		if (hasCmd) throw new Error("[E_SCRIPT_PARAMS] remote: scriptPath and cmd are alternative carriers — pass one");
+	}
+	if (args.commandId !== void 0 && (hasCmd || args.scriptPath !== void 0)) throw new Error("[E_PARAMS] remote: commandId guards a raw stdin write (stdin alone, no cmd/scriptPath) — drop it for a normal command");
+	if (args.stdin !== void 0 && !hasCmd && args.scriptPath === void 0) {
+		if (args.mode === "oneshot") throw new Error("[E_STDIN_WITHOUT_CMD] remote: oneshot has no interactive lane — stdin without cmd/scriptPath is a raw write into a PTY running command; drop mode:\"oneshot\" (or pass cmd)");
+		if (args.run_in_background === true) throw new Error("[E_PARAMS] remote: a raw stdin write cannot go background — it writes the command currently running in that PTY; follow it with job_output instead");
+		const r$1 = await ENV.driver.input(target, {
+			stdin: args.stdin,
+			...args.commandId !== void 0 ? { commandId: args.commandId } : {}
+		}, { sessionKey });
+		const handle = r$1.jobId ?? r$1.commandId;
+		return {
+			kind: "input",
+			text: `wrote ${r$1.writtenBytes} byte${r$1.writtenBytes === 1 ? "" : "s"} into ${r$1.session} for command ${r$1.commandId} — this confirms the write, not the program's response; read the response with job_output ${handle}`,
+			exit: null,
+			durationMs: 0,
+			session: r$1.session,
+			connection: r$1.connection,
+			...r$1.label !== void 0 ? { label: r$1.label } : {},
+			commandId: r$1.commandId,
+			...r$1.jobId !== void 0 ? { jobId: r$1.jobId } : {},
+			writtenBytes: r$1.writtenBytes
+		};
+	}
+	if (!hasCmd && args.scriptPath === void 0) throw new Error("[E_PARAMS] remote: action \"exec\" must execute something — pass cmd, or scriptPath for a local script file, or stdin alone for a raw write into a PTY running command");
 	if (args.run_in_background) {
-		if (!hasCmd && args.scriptPath === void 0) throw new Error("remote: background requires cmd or scriptPath");
 		const jobs = exec.agent?.ctx.get("jobs");
 		if (!jobs) throw new Error("remote: background requires the official DSH jobs service and job_output/job_kill controller; foreground execution remains available");
 		const lane = await ENV.driver.preparePtyLane({
 			target: args.target,
-			spawn: args.spawn,
 			cmd: args.cmd,
 			scriptPath: args.scriptPath,
-			ssh: args.ssh,
 			stdin: args.stdin,
-			timeout: args.timeout
-		}, { sessionKey: ENV.getSessionKey(exec) });
+			timeout: args.timeout,
+			...args.mode !== void 0 ? { mode: args.mode } : {}
+		}, { sessionKey });
 		let jobId;
 		try {
 			jobId = startRemoteJob(jobs, lane !== void 0 ? lane.input : {
 				target: args.target,
-				spawn: args.spawn,
 				cmd: args.cmd,
 				scriptPath: args.scriptPath,
-				ssh: args.ssh,
 				stdin: args.stdin,
-				timeout: args.timeout
+				timeout: args.timeout,
+				...args.mode !== void 0 ? { mode: args.mode } : {}
 			}, exec, ENV.driver);
 		} catch (error) {
 			lane?.cleanup();
@@ -4377,44 +5047,21 @@ async function remoteExecute(ENV, args, exec) {
 			durationMs: 0,
 			text: `Started ${jobId}${where}. Use job_output to read and job_kill to cancel; completion is reported by the host.`,
 			...lane !== void 0 ? {
+				commandId: jobId,
 				session: lane.session,
 				connection: lane.connection,
 				...lane.label !== void 0 ? { label: lane.label } : {}
 			} : {}
 		};
 	}
-	if (!hasCmd && args.scriptPath === void 0) {
-		if (args.stdin !== void 0) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd — status probes take no input");
-		const t = args.target ?? "";
-		if (hasSpawn || args.ssh !== void 0 || /^pty:/.test(t) || /:pty(:|$)/.test(t) && !t.startsWith("hub:")) return workbenchValue(await ENV.driver.call({
-			target: args.target,
-			spawn: args.spawn,
-			ssh: args.ssh,
-			cmd: "",
-			stdin: void 0
-		}, { sessionKey: ENV.getSessionKey(exec) }));
-		if (!hasTarget) return {
-			kind: "roster",
-			text: await ENV.driver.roster({ sessionKey: ENV.getSessionKey(exec) }),
-			exit: null,
-			durationMs: 0
-		};
-		return {
-			kind: "status",
-			text: await ENV.driver.status(args.target, { sessionKey: ENV.getSessionKey(exec) }),
-			exit: null,
-			durationMs: 0
-		};
-	}
 	const r = await ENV.driver.call({
 		target: args.target,
-		spawn: args.spawn,
-		ssh: args.ssh,
 		cmd: args.cmd,
 		scriptPath: args.scriptPath,
 		stdin: args.stdin,
-		timeout: args.timeout
-	}, { sessionKey: ENV.getSessionKey(exec) });
+		timeout: args.timeout,
+		...args.mode !== void 0 ? { mode: args.mode } : {}
+	}, { sessionKey });
 	const v = workbenchValue(r);
 	if (r.running === true && r.ptyJob !== void 0) {
 		const jobs = exec.agent?.ctx.get("jobs");
@@ -4422,7 +5069,7 @@ async function remoteExecute(ENV, args, exec) {
 			const jobId = adoptRunningPtyJob(jobs, exec, `${r.target}: ${args.cmd}`, r.ptyJob);
 			v.jobId = jobId;
 			v.running = true;
-			if (r.commandId !== void 0 && jobId !== r.commandId) ENV.driver.attachPtyJob(r.commandId, jobId, ENV.getSessionKey(exec));
+			if (r.commandId !== void 0 && jobId !== r.commandId) ENV.driver.attachPtyJob(r.commandId, jobId, sessionKey);
 		} else {
 			r.ptyJob.interrupt();
 			v.notice = "The command outlived its synchronous wait and no jobs service is available to poll it, so it was interrupted. Use run_in_background:true for long commands.";
@@ -4431,7 +5078,7 @@ async function remoteExecute(ENV, args, exec) {
 	return v;
 }
 function createRemoteTool(driver, opts = {}) {
-	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY$1);
 	const tool = defineTool({
 		name: "remote",
 		description: REMOTE_TOOL_DESCRIPTION,
@@ -4439,58 +5086,47 @@ function createRemoteTool(driver, opts = {}) {
 			action: {
 				type: "string",
 				enum: [
-					"copy",
-					"rsync",
+					"exec",
+					"handoff",
+					"add",
+					"status",
 					"close"
 				],
-				description: "Optional action; omit for execution/status/roster. close takes target + optional force."
-			},
-			force: {
-				type: "boolean",
-				description: "close only: default false — a session with a running job is refused (job_kill it first). true = kill the group and close in one step; the receipt lists what was killed."
+				required: true,
+				description: "Required. exec = run a command / script / raw stdin write (machine target defaults to its reusable PTY); handoff = detach a machine's default PTY as pty:<id>; add = register a BYO ssh identity or BYO PTY into the pool; status = roster (no target) or probe/session card (target); close = close a PTY shell (no job id — cancel with job_kill)."
 			},
-			src: {
+			target: {
 				type: "string",
-				description: "copy/rsync source [target:]absolute path; rsync retains trailing-slash semantics"
+				description: "exec: required — a machine (bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>; its default PTY unless mode is oneshot) or a live PTY session (pty:<id|label> or its bare label). handoff: the machine whose default PTY detaches. add: optional label for the BYO entry. status: optional — omit for the roster. close: a machine (its default PTY) or pty:<id|label>."
 			},
-			dst: {
+			cmd: {
 				type: "string",
-				description: "copy/rsync destination [target:]absolute path"
+				description: "exec: one raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Required unless scriptPath is given."
 			},
-			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\",\"-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",
-				items: { type: "string" },
-				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
+			stdin: {
+				type: "string",
+				description: "exec: with cmd/scriptPath = startup input (oneshot: piped; pty: REPL-style right after the command line; with scriptPath it is the script process's own stdin). Alone (no cmd/scriptPath) = a raw write into the PTY's RUNNING command — exact bytes; \"\" writes zero bytes (not EOF); \"\\n\" submits a line; \"\\u0003\" = Ctrl-C, \"\\u0004\" = Ctrl-D as raw characters; after a raw \"\\u0003\" settle the job with job_kill."
 			},
-			pushArgv: {
-				type: "array",
-				items: { type: "string" },
-				description: "Options for the PUSH half (origin staging → destination endpoint) of a two-command cross-endpoint copy. Mutually exclusive with argv; must be paired with pullArgv."
+			commandId: {
+				type: "string",
+				description: "exec stdin-only: optional guard — when given it must equal the running command's id (from the exec receipt or job_output); a stale id refuses the write instead of feeding the next command. Not valid with cmd/scriptPath."
 			},
-			verify: {
-				type: "boolean",
-				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."
+			timeout: {
+				type: "number",
+				description: "exec: per-command timeout in seconds (default 120). oneshot: interrupts then kills the whole group. pty: the command is NOT killed on timeout — it hands off to a running job you can poll (job_output) and cancel (job_kill = Ctrl-C first; the session survives an interrupt)."
 			},
-			mkdir: {
-				type: "boolean",
-				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."
+			mode: {
+				type: "string",
+				enum: ["pty", "oneshot"],
+				description: "exec: pty (default) — a machine target reuses its default interactive PTY (cwd/env persist); oneshot — isolated, stateless, stdout/stderr split, verbatim exit. Redundant on pty:<id|label> targets; \"oneshot\" on an addressable PTY is an error."
 			},
 			run_in_background: {
 				type: "boolean",
-				description: "oneshot AND pty: return a native jobId immediately, read with job_output, cancel with job_kill; output is available while running. On pty lanes the jobId IS the commandId — it tracks the running command inside a persistent session; job_kill sends Ctrl-C and the session survives. Hub-machine PTY has no background lane. Requires the official jobs service/controller."
-			},
-			target: {
-				type: "string",
-				description: "Single entry point. Machine targets: bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>. PTY: append :pty to create (ssh:dev4:pty, ssh:dev4:pty:build — label optional, every creation opens a new session) or address a live one with pty:<id|label>. BYO: pass spawn (pty) or ssh (identity) and the label lives in the same pool. Omit target → roster (or BYO auto-id when spawn/ssh present)."
+				description: "exec with cmd/scriptPath only: the command went async (not bash &) — a running job returns immediately and a completion notification will follow, so no polling is required. Oneshot runs async; on a machine's default PTY the framed command starts and that PTY is handed off in the same operation; on an addressable PTY it keeps its identity. job_output reads the command's full stream from byte 0 (overlap with the pre-handoff receipt is expected); job_kill cancels. Requires the official jobs service/controller."
 			},
 			ssh: {
 				type: "object",
-				description: "BYO ssh registration — the field present IS the entry point. First call registers (no cmd = register only); later calls reuse the label with ssh omitted. No inline keys or arbitrary SSH options.",
+				description: "add: BYO ssh identity to register into the pool (no dialing). Later exec calls address the returned label. No inline keys or arbitrary SSH options; nothing is persisted — a new Agent registers again.",
 				additionalProperties: false,
 				properties: {
 					host: {
@@ -4518,23 +5154,11 @@ function createRemoteTool(driver, opts = {}) {
 			},
 			spawn: {
 				type: "string",
-				description: "BYO pty creation — the field present IS the entry point: the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). Pairs with target pty[:<label>] / a bare <label> / nothing (auto id). Nested hops are dumb pipes (only the innermost bash frames)."
-			},
-			cmd: {
-				type: "string",
-				description: "One raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Omit with target → status/card; omit everything → roster."
-			},
-			scriptPath: {
-				type: "string",
-				description: "LOCAL absolute script path. Read before any dialing, sent literally over stdin to fixed bash -s. Oneshot only (no PTY lanes); cannot combine with cmd, stdin or spawn. Hub inline cmd remains limited to 4096; script body is not argv."
+				description: "add: BYO PTY entry point — the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). Pairs with target pty:<label> / a bare <label> / nothing (auto id). Nested hops are dumb pipes (only the innermost bash frames)."
 			},
-			stdin: {
-				type: "string",
-				description: "Input fed to the command. oneshot: piped to stdin. pty: written right after the command line (REPL-style). Requires cmd."
-			},
-			timeout: {
-				type: "number",
-				description: "Per-command timeout in seconds (default 120). oneshot: interrupts then kills the whole group. pty: the command is NOT killed on timeout — it hands off to a running job you can poll (job_output) and cancel (job_kill = Ctrl-C first; the session survives an interrupt)."
+			force: {
+				type: "boolean",
+				description: "close only: default false — a session with a running job is refused (job_kill it first). true = kill the group and close in one step; the receipt lists what was killed."
 			}
 		},
 		output: {
@@ -4547,12 +5171,12 @@ function createRemoteTool(driver, opts = {}) {
 						required: true,
 						enum: [
 							"exec",
+							"handoff",
 							"status",
 							"roster",
 							"job",
-							"copy",
-							"rsync",
-							"close"
+							"close",
+							"input"
 						]
 					},
 					text: {
@@ -4584,6 +5208,10 @@ function createRemoteTool(driver, opts = {}) {
 						type: "string",
 						description: "ledger key; equals the jobId whenever a job exists"
 					},
+					writtenBytes: {
+						type: "integer",
+						description: "input: UTF-8 bytes actually written; confirms the write, not the program response"
+					},
 					envDelta: {
 						type: "json",
 						description: "names only: {added,changed,removed}"
@@ -4592,7 +5220,7 @@ function createRemoteTool(driver, opts = {}) {
 					notice: { type: "string" },
 					runner: {
 						type: "string",
-						description: "oneshot supervision path: superd-run <ver> (<triple>) or posix-shim"
+						description: "oneshot supervision path: superd-run <ver> (<triple>), posix-shim, or hub-lease (peer hub server supervises natively)"
 					},
 					running: { type: "boolean" },
 					ttlSec: { type: "integer" },
@@ -4626,7 +5254,7 @@ function createRemoteTool(driver, opts = {}) {
 	const description = tool.description;
 	Object.defineProperty(tool, "description", {
 		enumerable: true,
-		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self). {} includes the Hub directory even when empty. Uses authenticated Hub HTTP oneshot / persistent WS PTY (hub:<m4>:pty selects the PTY lane); no SSH alias needed. Hub failures never fall back to SSH." : "")
+		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self; the roster lists them). Hub failures never fall back to SSH.\n- hub:<m4> oneshot: the peer hub server is the runner itself — bash -lc in a detached group, TERM→2s→KILL cleanup; the receipt runner field says \"hub-lease\" (the superd-run helper is a dumb-pipe artifact, never uploaded over the Hub). The peer caps inline commands at 4096 chars — and a scriptPath IS carried as one bash -c command, so hub-oneshot scripts share that cap (split large work or transfer the file and run it with cmd).\n- hub:<m4> as a machine target has the SAME default-PTY semantics as every other transport — exec opens the default session (a local pump child over one authenticated WebSocket to the peer terminal), handoff / background / stdin-only / close / idle TTL all work identically." : "")
 	});
 	return tool;
 }
@@ -4657,26 +5285,6 @@ function workbenchValue(r) {
 	if (r.ttlSec !== void 0) v.ttlSec = r.ttlSec;
 	return v;
 }
-/** 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 renderEnvDelta(d) {
 	const bits = [];
 	if (d.added.length > 0) bits.push(`+${d.added.join(",+")}`);
@@ -4685,7 +5293,7 @@ function renderEnvDelta(d) {
 	return bits.length > 0 ? bits.join(" ") : void 0;
 }
 function renderValue(v) {
-	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "copy" || v.kind === "rsync" || v.kind === "close") return v.text;
+	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "close" || v.kind === "input" || v.kind === "handoff") return v.text;
 	const parts = [];
 	if (v.reconnected === true) parts.push(RECONNECT_NOTICE);
 	if (typeof v.notice === "string" && v.notice.length > 0) parts.push(v.notice);
@@ -4706,15 +5314,188 @@ function renderValue(v) {
 	markers.push(`${secs}s`);
 	if (v.running === true) markers.push(`still running — poll job_output${v.jobId !== void 0 ? ` ${v.jobId}` : ""}`);
 	if (v.truncated !== void 0) markers.push(`truncated, ${v.outputStatsUnavailable ? "returned peer tail" : "original"} ${v.truncated} ${v.outputStats?.stdout.unit === "bytes" ? "bytes" : "chars"}`);
-	if (v.outputStatsUnavailable) markers.push("peer output totals/retention unavailable; returned tail only");
+	if (v.outputStatsUnavailable) markers.push("peer output totals/retention unavailable");
 	parts.push(`[${markers.join(" · ")}]`);
 	if (v.runner === "posix-shim" && (v.exit !== null && v.exit !== 0 || v.timedOut === true)) parts.push("note: this oneshot ran through the POSIX fallback on this target; PTY lanes use an independent lane and may still work here");
 	if (v.stderr !== void 0 && v.stderr.length > 0) parts.push("[stderr]", v.stderr);
 	return parts.join("\n");
 }
 
+//#endregion
+//#region src/remote/transfer-tool.ts
+const NO_SESSION_KEY = "remote:no-session";
+/**
+* The model-visible surface of the `remote_transfer` tool (split out of
+* `remote`, 2026-10-25). ONE template literal — no backticks, no "${".
+*/
+const TRANSFER_TOOL_DESCRIPTION = `File transfer between any two supported endpoints. Every call declares its mode:
+  mode:"copy"   → tree copy. Native CLI per endpoint (scp for ssh, docker cp, incus file push/pull), a plain tree copy when both ends are local, and the Hub binary lane when a Hub machine is involved. Directories copy recursively; exit codes are authoritative.
+  mode:"rsync"  → rsync over SSH only: at least one endpoint remote SSH, the other local or SSH (both remote legs tunnel through this machine; identities never leave it). Hub and container endpoints are rejected — no silent copy fallback. Trailing slashes keep rsync semantics.
+
+Endpoints are "[target:]absolute path". No target = the machine running this Agent. Targets are the same unified pool remote uses: a bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>. Examples: "/srv/app", "ssh:dev4:/srv/app", "docker:corti:/var/lib/x", "hub:m4:/srv". A path is never guessed: both operands must be absolute.
+
+Native CLI options travel through argv verbatim — one element = one token, appended before src/dst, no shell parsing and no whitelist: rsync ["-a","--partial"], scp ["-p","-r"], docker cp ["-a","-L"], incus file push ["--recursive"]. Cross-endpoint copies that need two commands (SSH↔Docker, SSH↔Incus, Docker↔Incus) take pullArgv plus pushArgv instead of argv. rsync is a single SSH command, so it takes argv only; an explicit -e/--rsh overrides the wiring.
+
+Options: verify (copy only) — the Hub↔local staged lane computes independent SHA-256 digests by default and verify:false skips them; native CLI routes have no independent hash tier, so verify is rejected there (self-verify through a oneshot digest command). mkdir (copy only, default true) — one best-effort pre-hop creates the destination PARENT directory; the operand itself is never pre-created, so each CLI's own layout semantics stay byte-identical.
+
+Failures are loud: a non-zero native exit throws with the receipt instead of returning a normal-looking result. The receipt stays in the receipt field (route, exits, verification, bytes/entries, cleanup); text is one formatted line. For checksum-grade verification of a native route, run a digest command through remote oneshot or PTY instead of trusting the copy receipt.`;
+const KNOWN_PARAMS = new Set([
+	"mode",
+	"src",
+	"dst",
+	"argv",
+	"pullArgv",
+	"pushArgv",
+	"verify",
+	"mkdir"
+]);
+async function transferExecute(ENV, args, exec) {
+	for (const key of Object.keys(args)) if (!KNOWN_PARAMS.has(key)) throw new Error(`remote_transfer: unknown parameter "${key}" — this surface has no legacy aliases; pass native CLI options through argv instead`);
+	if (args.mode !== "copy" && args.mode !== "rsync") throw new Error(`[E_PARAMS] remote_transfer: mode is required — "copy" (tree copy through each endpoint's native CLI or the Hub lane) or "rsync" (SSH only)`);
+	if (typeof args.src !== "string" || args.src.length === 0 || typeof args.dst !== "string" || args.dst.length === 0) throw new Error(`[E_PARAMS] remote_transfer: ${args.mode} requires src and dst absolute endpoints`);
+	const sessionKey = ENV.getSessionKey(exec);
+	if (args.mode === "rsync") {
+		if (args.pullArgv !== void 0 || args.pushArgv !== void 0) throw new Error("remote_transfer: rsync takes argv only; pullArgv/pushArgv are copy-only fields");
+		if (args.verify !== void 0 || args.mkdir !== void 0) throw new Error("remote_transfer: rsync cannot be combined with copy verify/mkdir options; the Hub/local staged lane is copy-only");
+		const start$1 = Date.now();
+		const receipt$1 = await ENV.driver.rsync({
+			src: args.src,
+			dst: args.dst,
+			...args.argv === void 0 ? {} : { argv: args.argv }
+		}, exec.signal, { sessionKey });
+		if (receipt$1.ok === false || receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
+		const durationMs$1 = Date.now() - start$1;
+		return {
+			kind: "rsync",
+			text: formatTransferLine("rsync", receipt$1, durationMs$1),
+			receipt: receipt$1,
+			exit: receipt$1.exit,
+			durationMs: durationMs$1
+		};
+	}
+	const start = Date.now();
+	const receipt = await ENV.driver.copy({
+		src: args.src,
+		dst: args.dst,
+		...args.verify === void 0 ? {} : { verify: args.verify },
+		...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
+		...args.argv === void 0 ? {} : { argv: args.argv },
+		...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
+		...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
+	}, exec.signal, { sessionKey });
+	const asReceipt = receipt;
+	const exits = asReceipt.exits ?? [];
+	if (asReceipt.ok === false || exits.some((code) => code !== 0)) throw new Error(JSON.stringify(receipt));
+	const durationMs = Date.now() - start;
+	return {
+		kind: "copy",
+		text: formatTransferLine("copy", receipt, durationMs),
+		receipt,
+		exit: exits.length > 0 ? 0 : null,
+		durationMs
+	};
+}
+function createRemoteTransferTool(driver, opts = {}) {
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	return defineTool({
+		name: "remote_transfer",
+		description: TRANSFER_TOOL_DESCRIPTION,
+		parameters: {
+			mode: {
+				type: "string",
+				enum: ["copy", "rsync"],
+				required: true,
+				description: "Required. copy = tree copy through each endpoint's native CLI, or the Hub binary lane; rsync = SSH only (argv only, no verify/mkdir)."
+			},
+			src: {
+				type: "string",
+				description: "Source [target:]absolute path. No target = the machine running this Agent."
+			},
+			dst: {
+				type: "string",
+				description: "Destination [target:]absolute path. No target = the machine running this Agent."
+			},
+			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\",\"-r\"], docker cp [\"-a\",\"-L\"], 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",
+				items: { type: "string" },
+				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
+			},
+			pushArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PUSH half (origin staging → destination endpoint) of a two-command cross-endpoint copy. Mutually exclusive with argv; must be paired with pullArgv."
+			},
+			verify: {
+				type: "boolean",
+				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, 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."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						enum: ["copy", "rsync"]
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					receipt: { type: "json" },
+					exit: { oneOf: [{ type: "integer" }, { type: "null" }] },
+					durationMs: { type: "integer" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args, exec) {
+			return transferExecute({
+				driver,
+				getSessionKey
+			}, args, exec);
+		}
+	});
+}
+/** 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(mode, receipt, durationMs) {
+	const r = receipt;
+	const parts = [];
+	if (r.ok === false) parts.push(`✗ ${r.reason ?? "failed"}`);
+	parts.push(`${mode} ${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(" · ");
+}
+
 //#endregion
 //#region src/remote/agent-registration.ts
+/** The pair a row contributes: execution/PTY and file transfer are separate tools. */
+const TOOL_NAMES = ["remote", "remote_transfer"];
 /** Host listeners attempt once per official creation edge, never on vacancy. */
 function installAgentRemote(ctx, config) {
 	return ctx.on("agent/created", ({ agent }) => {
@@ -4724,12 +5505,14 @@ function installAgentRemote(ctx, config) {
 			...config,
 			getHub: () => agent.ctx.get("superdRemoteTransport")
 		});
-		let unregister;
+		const registered = [];
 		try {
-			unregister = tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id }));
+			registered.push(tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id })));
+			registered.push(tools.register(createRemoteTransferTool(driver, { getSessionKey: () => agent.id })));
 		} catch (error) {
+			for (const undo of registered.splice(0)) undo();
 			driver.dispose();
-			if (error instanceof Error && error.message === "tool \"remote\" is already registered in this scope" && tools.get("remote", agent) !== void 0) return;
+			if (TOOL_NAMES.find((name$1) => error instanceof Error && error.message === `tool "${name$1}" is already registered in this scope` && tools.get(name$1, agent) !== void 0) !== void 0) return;
 			throw error;
 		}
 		const stopService = agent.ctx.on("internal/service", (name$1) => {
@@ -4741,7 +5524,7 @@ function installAgentRemote(ctx, config) {
 		const cleanup = () => {
 			if (disposal) return disposal;
 			disposal = driver.dispose();
-			unregister();
+			for (const undo of registered.splice(0)) undo();
 			stopService();
 			ownerUndo?.();
 			agentUndo?.();
@@ -4797,12 +5580,10 @@ const name = "dashr-remote";
 const inject = [];
 const Config = Schema.object({
 	execTimeoutSec: Schema.natural().min(1).default(120),
-	idleTtlSec: Schema.natural().min(1).default(REMOTE_PTY_IDLE_TTL_SEC),
-	maxOutputChars: Schema.natural().min(1).default(3e4)
+	idleTtlSec: Schema.natural().min(1).default(REMOTE_PTY_IDLE_TTL_SEC)
 }).default({
 	execTimeoutSec: 120,
-	idleTtlSec: REMOTE_PTY_IDLE_TTL_SEC,
-	maxOutputChars: 3e4
+	idleTtlSec: REMOTE_PTY_IDLE_TTL_SEC
 });
 /** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
 const apply = (ctx, config) => {
@@ -4816,4 +5597,4 @@ var plugin_default = {
 };
 
 //#endregion
-export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, Utf16TailRing, apply, checkAbsolute, checkSelection, plugin_default as default, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };
+export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, PtySession, Utf16TailRing, apply, buildHubPtyArgv, checkAbsolute, checkSelection, plugin_default as default, disclose, hubPtyAssets, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };