better-dsh 0.3.3 → 0.3.4-a

package/lib/remote/plugin.js

@@ -2,7 +2,7 @@ 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";
@@ -574,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;
@@ -613,6 +622,7 @@ function startBinaryProcess(argv, options = {}) {
 	const cancel = () => {
 		if (!finished) {
 			cancelled = true;
+			notifyCancel();
 			reap();
 		}
 	};
@@ -1611,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 §三"一层机械转义"）。 */
@@ -1783,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",
@@ -1857,18 +1726,21 @@ function buildHubPtyArgv(endpoint, assets) {
 /** 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",
@@ -1901,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",
@@ -1927,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",
@@ -1951,7 +1829,243 @@ function helperShellArgv(plan, script) {
 			script
 		];
 	}
-}
+}
+
+//#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.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 {
+		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). 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
@@ -2007,7 +2121,7 @@ function createNonceFrameParser(nonce, events) {
 	const prefix = `\x1b]133;D;${nonce};`;
 	const prefixE = `\x1b]133;E;${nonce};`;
 	const prefixes = [prefix, prefixE];
-	let buf = "";
+	let buf$1 = "";
 	let done = false;
 	const emit = (raw) => {
 		const text = normalizePtyText(raw);
@@ -2017,8 +2131,8 @@ function createNonceFrameParser(nonce, events) {
 	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))) {
+			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;
 			}
@@ -2031,7 +2145,7 @@ function createNonceFrameParser(nonce, events) {
 		let idx = -1;
 		let isEnv = false;
 		for (const p of prefixes) {
-			const i = buf.indexOf(p);
+			const i = buf$1.indexOf(p);
 			if (i >= 0 && (idx === -1 || i < idx)) {
 				idx = i;
 				isEnv = p === prefixE;
@@ -2039,26 +2153,26 @@ function createNonceFrameParser(nonce, events) {
 		}
 		if (idx < 0) {
 			const keep = holdback();
-			emit(buf.slice(0, buf.length - keep));
-			buf = buf.slice(buf.length - keep);
+			emit(buf$1.slice(0, buf$1.length - keep));
+			buf$1 = buf$1.slice(buf$1.length - keep);
 			return;
 		}
-		emit(buf.slice(0, idx));
-		const rest = buf.slice(idx + (isEnv ? prefixE.length : prefix.length));
+		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 = buf.slice(idx);
+				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({
@@ -2066,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 = "";
 		}
 	};
 }
@@ -2118,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 逐字。 */
@@ -2129,11 +2304,6 @@ 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 完成
@@ -2150,12 +2320,11 @@ var PtySession = class {
 	deathWaiters = [];
 	diag = "";
 	inFlight = 0;
+	cmdSeq = 0;
 	/** P4/P5：当前占用前台的 detached job（background/超时 handoff）。非 null 时新命令拒绝（Q6）。 */
 	detachedJob = null;
 	/** §3.2（2026-10-25）：当前占用会话的命令——dispatch 同步占位，settle/cleanup 释放；input 的唯一写入对象。 */
 	activeCommand = null;
-	/** 账本（§5）：本会话最近 20 条命令（FIFO，超出丢最旧）。 */
-	ledger = [];
 	/** env 侧信道基线（init E 帧）；undefined = 侧信道不可用（不报假 delta）。 */
 	envBaseline;
 	/** idle 起点（ready / settle 时重置）；null = 尚无 idle 时钟（cold 或已 dispose）。 */
@@ -2186,10 +2355,12 @@ var PtySession = class {
 	get detachedCommandId() {
 		return this.detachedJob?.commandId ?? null;
 	}
-	/** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId，账本如实记录两者）；运行中的命令同步携带（input 回执用）。 */
+	/** 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 标记。 */
@@ -2202,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;
@@ -2234,24 +2401,15 @@ var PtySession = class {
 		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}) — send it more stdin with the input action, 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`));
+			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;
-		const entry = {
-			commandId,
-			summary: summaryOf(cmd),
-			exit: null,
-			durationMs: 0,
-			running: true,
-			...dOpts.jobId !== void 0 ? { jobId: dOpts.jobId } : {}
-		};
-		this.ledger.push(entry);
-		if (this.ledger.length > LEDGER_MAX) this.ledger.shift();
 		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";
@@ -2260,8 +2418,6 @@ var PtySession = class {
 			const abandon = () => {
 				this.activeCommand = null;
 				this.inFlight--;
-				const index = this.ledger.indexOf(entry);
-				if (index >= 0) this.ledger.splice(index, 1);
 			};
 			if (this.state !== "ready") try {
 				await this.start();
@@ -2276,6 +2432,20 @@ var PtySession = class {
 			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;
@@ -2298,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() },
@@ -2324,6 +2501,16 @@ var PtySession = class {
 				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();
@@ -2331,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() },
@@ -2359,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);
@@ -2389,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();
@@ -2417,6 +2641,12 @@ var PtySession = class {
 		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)}`);
 		}
@@ -2433,6 +2663,11 @@ 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;
@@ -2479,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);
@@ -2540,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();
@@ -2752,50 +2998,20 @@ function parseTargetForm(target) {
 			form: "hub",
 			machine: segs[0]
 		};
-		if (segs.length === 2 && segs[1] === "pty") return {
-			form: "hub-pty",
-			machine: segs[0]
-		};
-		if (segs.length === 3 && segs[1] === "pty") {
-			if (segs[2] === void 0 || segs[2].length === 0) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — empty label after ":pty:"`);
-			return {
-				form: "hub-pty",
-				machine: segs[0],
-				label: segs[2]
-			};
-		}
-		throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — hub PTY is hub:<m4>:pty[:label]`);
+		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
@@ -2939,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",
@@ -2998,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
@@ -3154,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})`);
@@ -3176,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");
 }
@@ -3186,7 +3400,9 @@ 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）。 */
@@ -3202,6 +3418,10 @@ 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();
@@ -3214,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 });
 	}
@@ -3254,15 +3476,21 @@ 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 sessionKey = callCtx.sessionKey ?? "no-session";
 		const hasCmd = params.cmd !== void 0 && params.cmd.length > 0;
-		params.spawn !== void 0 && params.spawn.length;
+		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);
@@ -3459,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();
@@ -3501,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);
@@ -3552,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;
 		}
@@ -3672,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();
@@ -3701,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);
@@ -3750,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;
@@ -3763,42 +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}`,
-				byo: false,
-				...form.label !== void 0 ? { label: form.label } : {}
-			}, sessionKey) };
+				connection: `${entry.kind === "docker" ? "docker" : "incus"}:${entry.name}`
+			};
 		}
-		if (form.form === "hub-pty") {
-			const hub = this.requireHub();
-			this.hubProviders.add(hub);
-			const endpoint = hub.ptyEndpoint(form.machine);
-			const argv = this.opts.hubPtyArgvFor !== void 0 ? this.opts.hubPtyArgvFor(endpoint) : buildHubPtyArgv(endpoint, hubPtyAssets());
-			return { session: this.createSession({
-				argv,
-				connection: `hub:${form.machine}`,
+		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。 */
@@ -3810,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);
@@ -3827,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 {
@@ -3886,24 +4362,26 @@ var RemoteDriver = class {
 			this.pool.get(key)?.attachJob(commandId, jobId);
 		}
 	}
-	/** §3.1（2026-10-25）interactive-stdin：input 动作——向已有 live PTY 的当前运行命令
-	* 追加 stdin。只解析池内已存在的会话（pty:<id|label> / 裸 label 命中 pty 项），
-	* 不触发发现、拨号、创建或重连；machine target 与创建形（:pty 后缀，含 hub:<m4>:pty）
-	* 一律明确拒绝并给出可恢复指引。回执附 connection/label 供工具层渲染。 */
+	/** 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 selector;
+		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)");
-			selector = form.idOrLabel;
-		} else if (form.form === "bare") {
-			if (this.labels.resolve(form.name, sessionKey)?.kind !== "pty") throw new Error(`[E_NO_SESSION] remote: no live PTY session under ${JSON.stringify(form.name)} in this Agent's pool — input never dials, discovers or creates; run {action:"status"} to list sessions, then address one as pty:<id|label>`);
-			selector = form.name;
-		} else if (form.form === "create-pty" || form.form === "hub-pty") throw new Error(`[E_TARGET_FORMAT] remote: input writes into a live PTY session — "${target}" is a creation form; input never creates a session. Start the interactive program with {action:"exec", target:"${target}", cmd:…} first, then input into it`);
-		else throw new Error(`[E_TARGET_FORMAT] remote: input writes into a live PTY session — "${target}" is a machine target and machines are dialed per call. Run the interactive program with exec on a :pty session (e.g. {action:"exec", target:"ssh:dev4:pty" or "hub:<m4>:pty", cmd:…}), then input into that session`);
-		const session = this.resolvePty(selector, sessionKey);
+			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 {
@@ -3929,6 +4407,7 @@ var RemoteDriver = class {
 				jobId: commandId
 			} : {}
 		});
+		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 {
@@ -3992,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) {
 		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);
@@ -4085,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)");
@@ -4113,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");
 	}
@@ -4136,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");
@@ -4167,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 () => {
@@ -4177,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) {
@@ -4217,7 +4713,8 @@ const ptyOutcome = (aborted, result) => {
 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") {
+	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",
@@ -4354,83 +4851,32 @@ const NO_SESSION_KEY$1 = "remote:no-session";
 * interact-able stdin / managed output / persistent env——回执形状与 oneshot 相同、只增状态，
 * 运行中的命令可分步观察后再补输（input 动作）；多步与交互任务默认进 PTY。
 */
-const REMOTE_TOOL_DESCRIPTION = `Remote shell over ssh / docker / incus (Hub when configured): stateless oneshots + persistent interactive PTY sessions. Default to PTY for multi-step or interactive work; oneshot for isolated commands.
-
-Actions (action is the only dispatch dimension; unknown fields are rejected):
-- exec {target, cmd | scriptPath, stdin?, timeout?, run_in_background?}: run a command. Machine target → oneshot; pty:<id|label> → run inside that live session; <machine>:pty[:label] → create a NEW session and run there.
-- add {ssh:{...} | spawn:"<cmd>", target?}: register a BYO endpoint (identity or interactive-shell command); no command runs. Returns the addressable label; a taken label answers [E_LABEL_IN_USE] — address existing names directly, never add again.
-- status {}: roster — the one unified pool (machines, identities, live PTY sessions).
-- status {target}: machine probe, or a session card (connection, cwd, ledger of the last 20 commands).
-- input {target:"pty:<id|label>", stdin, commandId?}: write stdin into the command currently running in that session — passwords, OTP, tokens, menu choices, REPL lines. Never creates a session, never dials.
-- close {target, force?}: close a PTY session; a running command refuses it (job_kill first) unless force:true kills it in the same step.
-
-Targets:
-- ssh:<name> / docker:<name> / incus:<name> / bare pool name → stateless oneshot.
-- <machine>:pty[:label] → NEW PTY every call — creation is a target suffix, not a different tool.
-- pty:<id|label> (or its bare label) → REUSE the live session.
-After creation, reuse the returned session; repeating :pty opens another. Prefixes force the channel; bare names resolve through the roster.
-
-PTY:
-- stateful oneshot, interact-able stdin, managed output, persistent env
-- timeout (default 120s) → command keeps running; returns job handle.
-- run_in_background → same job lane. jobId = commandId.
-- Read: job_output(jobId). Cancel: job_kill; try Ctrl-C first.
-- Busy session: input / poll / cancel / use another session.
-- exec.stdin = startup input; input = subsequent input.
-- input is verbatim: "\\n" submits; "\\u0003" Ctrl-C; "\\u0004" Ctrl-D; "" writes nothing. Ctrl-D follows terminal EOF rules.
-- commandId, if supplied, must match running command.
-- Input receipt confirms write only; read result via SAME job.
-- Output returns in full up to retention (4M chars per stream; Hub oneshot 4MiB bytes) — beyond it the retained tail plus outputStats. Redirect bulk output to files.
-- Idle expiry: 15 min; running commands exempt.
-
-Oneshot:
-- stdout/stderr separate, exit code verbatim; no retained shell state. stdin is startup-only: there is no input after start — a prompt on a oneshot means cancel (job_kill) and switch to PTY. Heredocs and input redirection remain valid bulk-input alternatives.
-- Supervision prefers a pinned superd-run helper cached on the endpoint (~/.cache/superd/run), falls back to a POSIX shim — the receipt field "runner" says which ran. Either way children are reaped on completion and the whole group is killed on timeout/cancel. The endpoint needs bash only — no Python.
-- scriptPath (oneshot only): a LOCAL absolute script read before any dialing, sent literally over stdin to a fixed bash -s — the file carrier for multi-line scripts; pairs with neither cmd nor stdin.
-
-Examples
+const REMOTE_TOOL_DESCRIPTION = `Remote shell (SSH, Docker, Incus, Hub): 1 default interactive PTY per machine (retains cwd/env). \`mode:"oneshot"\` = isolated, stateless.
 
-Manage the persistent PTY session. One-shot style output, but stable: every command returns synchronously with exit, cwd, and an env delta.
+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\`.
 
-No direct route to the endpoint? Compose the transport and land the session on the innermost machine — bring your own PTY. Here: borrow pc as a jump host to reach dev4.
+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).
 
-remote { "action": "add", "spawn": "ssh -t pc ssh -t dev4", "target": "pty:dev4via" }
-
-[session created — address it as pty:pty-irsq]
-[pty:pty-irsq (dev4via) (byo-pty) · conn BYOP · idle-left ~15m · exit null · 0.0s]
-
-remote { "action": "exec", "target": "pty:dev4via", "cmd": "hostname && sudo -n ss -tlnp | awk 'NR==1 || /LISTEN/' | head -5" }
-
-dev4
-State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process
-LISTEN 0      4096   127.0.0.1:45207     0.0.0.0:*            users:(("containerd",pid=1070,fd=14))
-LISTEN 0      4096   127.0.0.1:2019      0.0.0.0:*            users:(("caddy",pid=5600,fd=4))
-LISTEN 0      4096   127.0.0.1:19514     0.0.0.0:*            users:(("multica",pid=27030,fd=6))
-LISTEN 0      4096   127.0.0.54:53       0.0.0.0:*             users:(("systemd-resolve",pid=26758,fd=17))
-[pty:pty-irsq (dev4via) (byo-pty) · conn BYOP · cmd remote-0d89215d1cc64cdc · cwd /home/u1 · idle-left ~15m · exit 0 · 0.3s]
-
-Reuse the same session for a long task — returns a jobId immediately; collect with job_output, cancel with job_kill:
-
-remote { "action": "exec", "target": "pty:dev4via", "cmd": "for i in 1 2 3; do sleep 1; echo \\"tick $i\\"; done; echo done", "run_in_background": true }
-
-Started remote-47676dff2c6443e8 on pty:pty-irsq (dev4via) (BYOP). Use job_output to read and job_kill to cancel; completion is reported by the host.
-
-job_output { "job_id": "remote-47676dff2c6443e8", "wait": true }
-
-tick 1
-tick 2
-tick 3
-done
-[status: completed, exit code: 0]
-
-- Bring Your Own PTY fits when the endpoint has no direct route, or the connection/transport layer must be composed yourself (jump chains, docker exec, console servers).
-- It also strips one or two shell-escaping layers — commands go straight to the innermost bash, quotes behave naturally.
-
-Register once — the label enters the pool and works everywhere: exec, pty, copy, rsync. Worth it whenever more than one operation type is involved. Keys stay local-file references; nothing persisted.
-
-remote { "action": "add", "ssh": { "host": "10.0.0.8", "user": "u1", "port": 22, "key": "/home/u1/.ssh/id_key4" }, "target": "ssh:lab" }
-remote { "action": "exec", "target": "ssh:lab", "cmd": "uname -a" }
-remote_transfer { "mode": "rsync", "src": "ssh:lab:/var/log/app/", "dst": "/home/u1/app-logs/", "argv": ["-a"] }`;
+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([
@@ -4440,8 +4886,11 @@ const ACTION_PARAMS = {
 		"stdin",
 		"scriptPath",
 		"timeout",
-		"run_in_background"
+		"run_in_background",
+		"mode",
+		"commandId"
 	]),
+	handoff: new Set(["action", "target"]),
 	add: new Set([
 		"action",
 		"target",
@@ -4453,26 +4902,20 @@ const ACTION_PARAMS = {
 		"action",
 		"target",
 		"force"
-	]),
-	input: new Set([
-		"action",
-		"target",
-		"stdin",
-		"commandId"
 	])
 };
 const ACTION_HINT = {
-	exec: "exec takes target plus cmd (or scriptPath) and the execution options; ssh/spawn belong to add",
+	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 target pty:<id|label> and optional force",
-	input: "input takes target (a live PTY session), stdin, and an optional commandId guard — no cmd, no timeout, no creation"
+	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) {
 	const action = args.action;
-	if (action === void 0) throw new Error("[E_PARAMS] remote: action is required — \"exec\" (run a command), \"add\" (register a BYO endpoint), \"status\" (roster / probe / session card), \"close\" (close a PTY session), \"input\" (append stdin to a running PTY command)");
+	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 / add / close / status / input`);
+	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;
@@ -4491,40 +4934,38 @@ async function remoteExecute(ENV, args, exec) {
 			durationMs: 0
 		};
 	}
-	if (action === "close") {
-		if (!hasTarget) throw new Error("[E_PARAMS] close requires target pty:<id|label>");
-		const r$1 = ENV.driver.closePty(args.target.startsWith("pty:") ? args.target.slice(4) : args.target, sessionKey, args.force === true);
+	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: "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"}`,
+			kind: "handoff",
+			text: r$1.stdout,
 			exit: null,
 			durationMs: 0,
 			session: r$1.session,
-			closed: r$1.closed,
-			...r$1.reason !== void 0 ? { reason: r$1.reason } : {},
-			killed: r$1.killed
+			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 (action === "input") {
-		if (!hasTarget) throw new Error("[E_PARAMS] remote: action \"input\" requires target — the live PTY session whose command is waiting (pty:<id|label> or its bare label)");
-		if (args.stdin === void 0) throw new Error("[E_PARAMS] remote: action \"input\" requires stdin — the exact text to append; include a trailing \\n to submit a line, \"\\u0003\" for Ctrl-C, \"\\u0004\" for Ctrl-D (\"\" = zero bytes, not EOF)");
-		if (typeof args.commandId === "string" && args.commandId.length === 0) throw new Error("[E_PARAMS] remote: input: commandId, when given, must be the non-empty id from the exec receipt / job_output");
-		const r$1 = await ENV.driver.input(args.target, {
-			stdin: args.stdin,
-			...args.commandId !== void 0 ? { commandId: args.commandId } : {}
-		}, { sessionKey });
-		const handle = r$1.jobId ?? r$1.commandId;
+	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: "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}`,
+			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"}`,
 			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
+			closed: r$1.closed,
+			...r$1.reason !== void 0 ? { reason: r$1.reason } : {},
+			killed: r$1.killed
 		};
 	}
 	if (action === "add") {
@@ -4545,15 +4986,34 @@ async function remoteExecute(ENV, args, exec) {
 	}
 	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;
-	const ptyTarget = /^pty:/.test(target) || /:pty(:|$)/.test(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 (ptyTarget) throw new Error("[E_SCRIPT_PARAMS] remote: scriptPath is oneshot-only — PTY lanes take cmd");
 		if (hasCmd) throw new Error("[E_SCRIPT_PARAMS] remote: scriptPath and cmd are alternative carriers — pass one");
-		if (args.stdin !== void 0) throw new Error("[E_SCRIPT_PARAMS] remote: scriptPath already occupies stdin — do not pass stdin with it");
 	}
-	if (args.stdin !== void 0 && !hasCmd) throw new Error("[E_STDIN_WITHOUT_CMD] remote: exec stdin is startup input and requires cmd — to feed a command that is already running in a PTY, use {action:\"input\", target:\"pty:<id|label>\", stdin}");
-	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");
+	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) {
 		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");
@@ -4562,7 +5022,8 @@ async function remoteExecute(ENV, args, exec) {
 			cmd: args.cmd,
 			scriptPath: args.scriptPath,
 			stdin: args.stdin,
-			timeout: args.timeout
+			timeout: args.timeout,
+			...args.mode !== void 0 ? { mode: args.mode } : {}
 		}, { sessionKey });
 		let jobId;
 		try {
@@ -4571,7 +5032,8 @@ async function remoteExecute(ENV, args, exec) {
 				cmd: args.cmd,
 				scriptPath: args.scriptPath,
 				stdin: args.stdin,
-				timeout: args.timeout
+				timeout: args.timeout,
+				...args.mode !== void 0 ? { mode: args.mode } : {}
 			}, exec, ENV.driver);
 		} catch (error) {
 			lane?.cleanup();
@@ -4597,7 +5059,8 @@ async function remoteExecute(ENV, args, exec) {
 		cmd: args.cmd,
 		scriptPath: args.scriptPath,
 		stdin: args.stdin,
-		timeout: args.timeout
+		timeout: args.timeout,
+		...args.mode !== void 0 ? { mode: args.mode } : {}
 	}, { sessionKey });
 	const v = workbenchValue(r);
 	if (r.running === true && r.ptyJob !== void 0) {
@@ -4624,17 +5087,17 @@ function createRemoteTool(driver, opts = {}) {
 				type: "string",
 				enum: [
 					"exec",
+					"handoff",
 					"add",
 					"status",
-					"close",
-					"input"
+					"close"
 				],
 				required: true,
-				description: "Required. exec = run a command (oneshot on a machine, or inside a PTY session); 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 session; input = append stdin to the command currently running in a live PTY session."
+				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)."
 			},
 			target: {
 				type: "string",
-				description: "exec: required. A machine (bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>), a live PTY session (pty:<id|label> or its bare label), or a machine with :pty[:label] to create a new session (ssh:dev4:pty, hub:<m4>:pty, ssh:dev4:pty:build). add: optional label for the BYO entry. status: optional — omit for the roster. close / input: pty:<id|label> (input never creates or dials — the session must already run the command)."
+				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>."
 			},
 			cmd: {
 				type: "string",
@@ -4642,19 +5105,24 @@ function createRemoteTool(driver, opts = {}) {
 			},
 			stdin: {
 				type: "string",
-				description: "exec: startup input fed to cmd — oneshot: piped to stdin; pty: written right after the command line (REPL-style); requires cmd. input: the exact text to append to the RUNNING command — \"\" writes zero bytes (not EOF); include \"\\n\" to submit a line; \"\\u0003\" = Ctrl-C, \"\\u0004\" = Ctrl-D as raw characters."
+				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."
 			},
 			commandId: {
 				type: "string",
-				description: "input 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. Ignored by other actions."
+				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."
 			},
 			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)."
 			},
+			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: "exec: 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. Requires the official jobs service/controller."
+				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",
@@ -4686,7 +5154,7 @@ function createRemoteTool(driver, opts = {}) {
 			},
 			spawn: {
 				type: "string",
-				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)."
+				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)."
 			},
 			force: {
 				type: "boolean",
@@ -4703,6 +5171,7 @@ function createRemoteTool(driver, opts = {}) {
 						required: true,
 						enum: [
 							"exec",
+							"handoff",
 							"status",
 							"roster",
 							"job",
@@ -4785,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; 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). Inline cmd is limited to 4096 chars; scriptPath is the file carrier and is not argv.\n- hub:<m4>:pty[:label] opens the SAME persistent interactive session as every other transport — id, label, input, busy, timeout handoff, background, close, session card, ledger, idle TTL, quota — carried by a local pump child over one authenticated WebSocket to the peer terminal." : "")
+		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;
 }
@@ -4824,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 === "close" || v.kind === "input") 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);