better-dsh 0.3.1 → 0.3.2-d

package/lib/remote/plugin.js

@@ -1,15 +1,18 @@
-import { t as Schema } from "../lib-C8_jXvwA.js";
+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, mkdirSync, statSync } from "node:fs";
+import { constants, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
-import { homedir, tmpdir } from "node:os";
 import { createConnection, createServer } from "node:net";
+import { Buffer as Buffer$1 } from "node:buffer";
 
 //#region src/remote/archive.ts
 const FILE_FRAME_BYTES = 64 * 1024;
@@ -317,17 +320,18 @@ async function copyTree(request, source, destination, signal, scratchRoot = join
 	signal.throwIfAborted();
 	if (request.argv !== void 0 || request.pullArgv !== void 0 || request.pushArgv !== void 0) throw new Error("copy: argv/pullArgv/pushArgv are native CLI options; the Hub/local staged lane does not accept CLI options");
 	await mkdir(scratchRoot, { recursive: true });
-	signal.throwIfAborted();
-	const scratch = await mkdtemp(join(scratchRoot, "remote-copy-")), payload = join(scratch, "payload.bin");
 	const receipt = {
 		action: "copy",
+		route: "hub-staged",
 		src: request.src,
 		dst: request.dst,
-		verified: false,
+		ok: false,
+		verification: "not-applicable",
 		bytes: 0,
 		entries: 0,
 		scope: "transferred entries"
 	};
+	const scratch = await mkdtemp(join(scratchRoot, "remote-copy-")), payload = join(scratch, "payload.bin");
 	try {
 		await pipeline(await source.endpoint.exportTree(source.path, signal), createWriteStream(payload, {
 			flags: "wx",
@@ -351,24 +355,91 @@ async function copyTree(request, source, destination, signal, scratchRoot = join
 			const dest = await destination.endpoint.digest(destination.path, signal, selection);
 			receipt.destinationDigest = dest.sha256;
 			if (dest.sha256 !== receipt.sourceDigest) throw new Error("destination digest mismatch");
-			receipt.verified = true;
+			receipt.verification = "sha256";
 		}
 		signal.throwIfAborted();
 		await rm(scratch, {
 			recursive: true,
 			force: true
 		});
+		receipt.ok = true;
 		return receipt;
 	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const reason = signal.aborted ? "aborted" : /mismatch/i.test(message) ? "digest-mismatch" : "staging-error";
 		throw new CopyError({
 			...receipt,
-			verified: false,
+			ok: false,
+			reason,
 			scratch,
-			error: error instanceof Error ? error.message : String(error)
+			error: message
 		});
 	}
 }
 
+//#endregion
+//#region src/remote/ssh-argv.ts
+/**
+* ONE identity-assembly policy for every SSH-speaking lane (user close-out
+* ruling 2026-10-17: "four builders necessarily mean four identity
+* semantics" — the structural root of F1).
+*
+* Assembly: explicit connection fields (byossh registrations; caller options
+* may override later by the CLI's own last-option-wins) in ONE order —
+* user, port, key, proxyJump — spoken in the target CLI's dialect.
+*
+* Resolution: config-side identity (aliases, config-only IdentityFile paths)
+* is read from the ORIGIN's own ssh config natively by every lane. The single
+* exception is the scp -3 temp config (ssh -F sees no user config), where
+* tempSshConfig inlines the `ssh -G`-resolved fields — paths only, never key
+* material (F1, 2026-10-14). That policy lives beside this builder in
+* native-copy.ts and must stay the only such inline site.
+*
+* Former duplicate builders now reduced here: sshArgv (execution/probes),
+* identityArgv (scp routes), rsyncRsh (RSYNC_RSH wiring), relaySsh
+* (dual-SSH relay). Behavior is byte-identical to each former site.
+*/
+/** Identity options ONLY for one connection, in the target CLI's dialect:
+* user, port, key, proxyJump — conditional, one order, NO base flags (each
+* lane's dialect base — BatchMode, -T, hardening — stays at its call site).
+* scp carries the user inside its user@host operand, so the scp dialect
+* never emits -l; its port flag is -P. */
+function sshIdentityArgv(connection, dialect) {
+	const args = [];
+	if (dialect === "ssh" && connection.user !== void 0) args.push("-l", connection.user);
+	if (connection.port !== void 0) args.push(dialect === "scp" ? "-P" : "-p", String(connection.port));
+	if (connection.key !== void 0) args.push("-i", connection.key);
+	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
+	return args;
+}
+/** Full ssh invocation around the shared identity core. base and extra are
+* trusted internal argv (dialect flags incl. BatchMode, forwarding options)
+* — never a model-provided shell string. */
+/** SSH keepalive for PERSISTENT lanes (pty ruling 2026-10-19): client-owned,
+* fixed cadence — OpenSSH has NO protocol-default keepalive unit (default is
+* disabled), so we set our own in our own argv. Control-channel probes never
+* touch the PTY byte stream; NAT/WiFi idle expiry (~5min) would otherwise
+* silently kill an idle-but-wanted session inside the 15min TTL. CountMax=2
+* gives ~6min honest dead-detection instead of a hang on next write. */
+const SSH_PERSISTENT_KEEPALIVE = [
+	"-o",
+	"ServerAliveInterval=180",
+	"-o",
+	"ServerAliveCountMax=2"
+];
+function sshCommandArgv(connection, base, extra, command) {
+	const args = [
+		"ssh",
+		...base,
+		...sshIdentityArgv(connection, "ssh"),
+		...extra,
+		"--",
+		connection.host
+	];
+	if (command !== void 0) args.push(command);
+	return args;
+}
+
 //#endregion
 //#region src/remote/output-ring.ts
 const continuation = (byte) => (byte & 192) === 128;
@@ -674,15 +745,17 @@ function scpSpec(connection, path$1) {
 	const host = connection.host.includes(":") ? `[${connection.host}]` : connection.host;
 	return `${connection.user !== void 0 ? `${connection.user}@${host}` : host}:${path$1}`;
 }
-/** Connection identity as scp options (port, key), placed BEFORE caller argv so
-* an explicit caller -F/-i/-P/-J overrides the registered identity by scp's own
-* precedence (last option wins). */
+/** Connection identity as scp options, placed BEFORE caller argv so an
+* explicit caller -F/-i/-P/-J overrides the registered identity by scp's own
+* precedence (last option wins). Assembly itself lives in ssh-argv.ts
+* (the ONE identity policy — 2026-10-17 ruling); only the scp dialect
+* placement rule is local. */
 function identityArgv(connection) {
-	const options = ["-o", "BatchMode=yes"];
-	if (connection.port !== void 0) options.push("-P", String(connection.port));
-	if (connection.key !== void 0) options.push("-i", connection.key);
-	if (connection.proxyJump !== void 0) options.push("-J", connection.proxyJump);
-	return options;
+	return [
+		"-o",
+		"BatchMode=yes",
+		...sshIdentityArgv(connection, "scp")
+	];
 }
 function sshEndpoint(plan) {
 	if (plan.kind !== "ssh") throw new Error("remote: native copy endpoint is not an SSH target");
@@ -721,24 +794,30 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 		stdout: [],
 		stderr: [],
 		outputTruncated: false,
-		verified: false,
+		verification: "native-exit-only",
+		ok: true,
 		cleanup: "none-required"
 	};
-	const finish = (route, argvs, results) => {
+	const finish = (route, argvs, results, internal = []) => {
 		receipt.route = route;
-		receipt.argv = argvs;
+		receipt.argv = argvs.map((argv) => argv.map((token) => internal.find(([secret]) => secret === token)?.[1] ?? token));
 		receipt.exits = results.map((result) => result.exit);
 		receipt.stdout = results.map((result) => result.stdout);
 		receipt.stderr = results.map((result) => result.stderr);
 		receipt.outputTruncated = results.some((result) => result.outputTruncated);
+		receipt.ok = !signal.aborted && receipt.exits.every((exit) => exit === 0);
+		if (!receipt.ok) receipt.reason = signal.aborted ? "aborted" : "non-zero-exit";
 		return receipt;
 	};
+	if (request.mkdir !== false) await ensureDestinationDir(endpoints.dst, signal, options.execArgvFor, wrap, receipt);
+	else receipt.created = "n-a";
 	if (s === "local" && t === "ssh") {
 		rejectRemoteToRemoteScp(oneShot);
 		const connection = sshEndpoint(endpoints.dst.plan).connection;
 		const argv = [
 			"scp",
 			...identityArgv(connection),
+			...await recursiveFlag(endpoints.src.path, oneShot, "-r"),
 			...oneShot,
 			endpoints.src.path,
 			scpSpec(connection, endpoints.dst.path)
@@ -771,7 +850,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 				dstSpec = scpSpec(destination, endpoints.dst.path);
 				extra = identityArgv(source);
 			} else {
-				config = await tempSshConfig(source, destination);
+				config = await tempSshConfig(source, destination, runNative);
 				extra = ["-F", config.path];
 				srcSpec = `superd-scp3-source:${endpoints.src.path}`;
 				dstSpec = `superd-scp3-destination:${endpoints.dst.path}`;
@@ -784,7 +863,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 				srcSpec,
 				dstSpec
 			];
-			return finish("scp -3 (data through origin)", [argv], [await runNative(wrap(argv), signal)]);
+			return finish("scp-3", [argv], [await runNative(wrap(argv), signal)], config !== void 0 ? [[config.path, "<temp-ssh-config>"]] : []);
 		} catch (error) {
 			if (signal.aborted) unknown = true;
 			throw error;
@@ -803,7 +882,9 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 			endpoints.src.path,
 			`${containerOf(endpoints.dst.plan)}:${endpoints.dst.path}`
 		];
-		return finish("docker cp", [argv], [await runNative(wrap(argv), signal)]);
+		const result = await runNative(wrap(argv), signal);
+		withSymlinkHint(result);
+		return finish("docker-cp", [argv], [result]);
 	}
 	if (s === "docker" && t === "local") {
 		const argv = [
@@ -813,18 +894,21 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 			`${containerOf(endpoints.src.plan)}:${endpoints.src.path}`,
 			endpoints.dst.path
 		];
-		return finish("docker cp", [argv], [await runNative(wrap(argv), signal)]);
+		const result = await runNative(wrap(argv), signal);
+		withSymlinkHint(result);
+		return finish("docker-cp", [argv], [result]);
 	}
 	if (s === "local" && t === "incus") {
 		const argv = [
 			"incus",
 			"file",
 			"push",
+			...await recursiveFlag(endpoints.src.path, oneShot, "-r"),
 			...oneShot,
 			endpoints.src.path,
 			`${containerOf(endpoints.dst.plan)}${endpoints.dst.path}`
 		];
-		return finish("incus file push", [argv], [await runNative(wrap(argv), signal)]);
+		return finish("incus-file-push", [argv], [await runNative(wrap(argv), signal)]);
 	}
 	if (s === "incus" && t === "local") {
 		const argv = [
@@ -835,7 +919,7 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 			`${containerOf(endpoints.src.plan)}${endpoints.src.path}`,
 			endpoints.dst.path
 		];
-		return finish("incus file pull", [argv], [await runNative(wrap(argv), signal)]);
+		return finish("incus-file-pull", [argv], [await runNative(wrap(argv), signal)]);
 	}
 	if (s === "local" || t === "local") throw new Error("remote: this endpoint pair is a single native command route; pullArgv/pushArgv apply to cross-endpoint pairs only");
 	const pullOptions = request.pullArgv !== void 0 ? pull : oneShot;
@@ -848,9 +932,12 @@ async function nativeCopy(request, endpoints, signal, options = {}) {
 		const pullArgv = segmentArgv(endpoints.src.plan, endpoints.src.path, staged, pullOptions, "pull");
 		const pushArgv = segmentArgv(endpoints.dst.plan, endpoints.dst.path, staged, pushOptions, "push");
 		const first = await runNative(wrap(pullArgv), signal);
-		if (first.exit !== 0) return finish("two native commands with origin staging (push not started: pull failed)", [pullArgv], [first]);
+		if (first.exit !== 0) {
+			receipt.note = "push not started: pull failed";
+			return finish("staged-pull-push", [pullArgv], [first], [[staged, "<staging>"]]);
+		}
 		const second = await runNative(wrap(pushArgv), signal);
-		return finish("two native commands with origin staging", [pullArgv, pushArgv], [first, second]);
+		return finish("staged-pull-push", [pullArgv, pushArgv], [first, second], [[staged, "<staging>"]]);
 	} finally {
 		receipt.cleanup = await rm(scratch, {
 			recursive: true,
@@ -911,40 +998,162 @@ function segmentArgv(plan, remote, staged, opts, leg) {
 		spec
 	];
 }
+/** D3 mkdir pre-hop: ensure the destination's PARENT directory exists before
+* the transfer (never the operand itself — see parent-only note below).
+* transfer. Local dst is node-side; remote dst runs ONE exec `mkdir -p` probe
+* whose stdout discloses created-vs-existed. Best-effort by contract: any
+* failure records created:'n-a' + note and lets the copy proceed so the native
+* CLI surfaces the real error (and stopped-container docker cp keeps working). */
+async function ensureDestinationDir(dst, signal, execArgvFor, wrap, receipt) {
+	const dir = dirname(dst.path);
+	if (dir === "/" || dir === ".") {
+		receipt.created = false;
+		return;
+	}
+	if (dst.plan.kind === "local") {
+		try {
+			if (existsSync(dir)) {
+				receipt.created = false;
+				return;
+			}
+			mkdirSync(dir, { recursive: true });
+			receipt.created = true;
+		} catch (error) {
+			receipt.created = "n-a";
+			receipt.note = `mkdir pre-hop failed: ${error instanceof Error ? error.message : String(error)}`;
+		}
+		return;
+	}
+	if (execArgvFor === void 0) {
+		receipt.created = "n-a";
+		return;
+	}
+	if (/[\r\n]/.test(dir)) {
+		receipt.created = "n-a";
+		receipt.note = "mkdir pre-hop skipped: newline-bearing destination path";
+		return;
+	}
+	const quoted = `'${dir.replaceAll("'", "'\\\\''")}'`;
+	const script = `if [ -d ${quoted} ]; then echo existed; else mkdir -p ${quoted} && echo created; fi`;
+	try {
+		const result = await runNative(wrap(execArgvFor(dst.plan, script)), signal);
+		const word = result.stdout.trim().split("\n").pop();
+		if (result.exit === 0 && word === "created") receipt.created = true;
+		else if (result.exit === 0 && word === "existed") receipt.created = false;
+		else {
+			receipt.created = "n-a";
+			const tail = result.stderr.trim().split("\n").filter((line) => line.length > 0).pop();
+			receipt.note = `mkdir pre-hop unavailable (exit ${result.exit})${tail !== void 0 ? `: ${tail}` : ""}`;
+		}
+	} catch (error) {
+		receipt.created = "n-a";
+		receipt.note = `mkdir pre-hop failed: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
 /** Distinguishing identities for scp -3: an origin-only temp config maps two
 * synthetic aliases; keys are referenced in place, never copied to any remote. */
-async function tempSshConfig(source, destination) {
-	for (const c of [source, destination]) for (const [field, value] of [
-		["host", c.host],
-		["user", c.user],
-		["key", c.key],
-		["proxyJump", c.proxyJump]
-	]) if (value !== void 0 && /[\r\n]/.test(value)) throw new Error(`remote: scp -3 temp config rejects newline in SSH ${field} (no config injection)`);
+/** D8 (2026-10-14 user adoption, third acceptance round): a LOCAL directory source gets
+*  the route's recursive flag appended automatically — scp / incus file push refuse
+*  directories without it. The appended flag lands in the executed argv, which the
+*  receipt shows verbatim: disclosure by receipt, never silent. Remote sources stay
+*  caller-explicit (we do not dial just to stat); an explicit caller flag wins. */
+async function recursiveFlag(localPath, callerArgv, flag) {
+	if (callerArgv.includes(flag) || callerArgv.includes("--recursive")) return [];
+	try {
+		if ((await stat(localPath)).isDirectory()) return [flag];
+	} catch {}
+	return [];
+}
+/** docker cp follows symlinks only with -L; its native error ("invalid symlink")
+*  names no remedy. Append the one-line hint on that failure path (F5, 2026-10-14). */
+function withSymlinkHint(result) {
+	if (result.exit !== 0 && /invalid symlink/i.test(result.stderr)) result.stderr = `${result.stderr}\nhint: docker cp follows symlinks only with -L — pass argv:["-L"] (e.g. /etc/os-release is a symlink)`;
+}
+async function tempSshConfig(source, destination, runNative$1) {
+	const resolvedSource = await resolveThroughOriginConfig(source, runNative$1);
+	const resolvedDestination = await resolveThroughOriginConfig(destination, runNative$1);
+	for (const { connection: c, identityFiles } of [resolvedSource, resolvedDestination]) {
+		for (const [field, value] of [
+			["host", c.host],
+			["user", c.user],
+			["key", c.key],
+			["proxyJump", c.proxyJump]
+		]) if (value !== void 0 && /[\r\n]/.test(value)) throw new Error(`remote: scp -3 temp config rejects newline in SSH ${field} (no config injection)`);
+		for (const idFile of identityFiles) if (/[\r\n]/.test(idFile)) throw new Error("remote: scp -3 temp config rejects newline in resolved IdentityFile (no config injection)");
+	}
 	const dir = await mkdtemp(join(tmpdir(), "superd-scp3-"));
 	const path$1 = join(dir, "config");
-	const block = (name$1, c) => {
+	const block = (name$1, c, identityFiles) => {
 		const lines = [`Host ${name$1}`, `  HostName ${c.host.replace(/^.*@/, "")}`];
 		if (c.user !== void 0) lines.push(`  User ${c.user}`);
 		if (c.port !== void 0) lines.push(`  Port ${String(c.port)}`);
-		if (c.key !== void 0) lines.push(`  IdentityFile ${c.key}`);
+		for (const idFile of [c.key !== void 0 ? [c.key] : [], identityFiles].flat()) lines.push(`  IdentityFile ${idFile}`);
 		if (c.proxyJump !== void 0) lines.push(`  ProxyJump ${c.proxyJump}`);
 		return lines.join("\n");
 	};
-	await writeFile(path$1, `${block("superd-scp3-source", source)}\n${block("superd-scp3-destination", destination)}\n`, { mode: 384 });
+	await writeFile(path$1, `${block("superd-scp3-source", resolvedSource.connection, resolvedSource.identityFiles)}\n${block("superd-scp3-destination", resolvedDestination.connection, resolvedDestination.identityFiles)}\n`, { mode: 384 });
 	await chmod(path$1, 384);
 	return {
 		path: path$1,
 		dir
 	};
 }
+/** Effective fields for one connection per the origin's own ssh config (ssh -G,
+*  prints resolved settings without dialing). Explicit fields win; empty/none
+*  proxyjump is dropped. IdentityFile PATHS from the config are returned separately
+*  for inlining into the temp config — a path is not key material and stays on the
+*  origin (F1, 2026-10-14: dev4's only authorized key lived in config, not the agent;
+*  dropping it made scp -3 fail with a bare Permission denied). */
+async function resolveThroughOriginConfig(c, runNative$1) {
+	let probe;
+	try {
+		probe = await runNative$1([
+			"ssh",
+			"-G",
+			c.host
+		], new AbortController().signal);
+	} catch {
+		probe = void 0;
+	}
+	if (probe === void 0 || probe.exit !== 0) return {
+		connection: c,
+		identityFiles: []
+	};
+	const lines = probe.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	const pick = (key) => lines.find((line) => line.startsWith(`${key} `))?.slice(key.length + 1).trim() || void 0;
+	const home = process.env.HOME ?? "";
+	const compiledDefault = (path$1) => path$1 === "none" || [
+		"id_rsa",
+		"id_ecdsa",
+		"id_ecdsa_sk",
+		"id_ed25519",
+		"id_ed25519_sk"
+	].some((name$1) => path$1 === `~/.ssh/${name$1}` || home !== "" && path$1 === `${home}/.ssh/${name$1}`);
+	const identityFiles = [...new Set(lines.filter((line) => line.startsWith("identityfile ")).map((line) => line.slice(13).trim()).filter((path$1) => path$1 !== "" && !compiledDefault(path$1)))];
+	const host = (pick("hostname") ?? c.host).replace(/^.*@/, "");
+	const user = c.user ?? pick("user");
+	const portText = pick("port");
+	const port = c.port ?? (portText !== void 0 && /^\d+$/.test(portText) ? Number(portText) : void 0);
+	const proxyJumpRaw = c.proxyJump ?? pick("proxyjump");
+	return {
+		connection: {
+			host,
+			...user !== void 0 && user !== "" ? { user } : {},
+			...port !== void 0 && Number.isInteger(port) && port > 0 ? { port } : {},
+			...c.key !== void 0 ? { key: c.key } : {},
+			...proxyJumpRaw !== void 0 && proxyJumpRaw !== "" && proxyJumpRaw.toLowerCase() !== "none" ? { proxyJump: proxyJumpRaw } : {}
+		},
+		identityFiles
+	};
+}
 
 //#endregion
 //#region src/remote/ssh-rsync-native-relay.ts
 /** ssh argv for the relay: batch, no agent, no multiplexing. `command` is the
-* remote command; forwarding options go before `--`, the host after it. */
+* remote command; forwarding options go before `--`, the host after it.
+* Identity core comes from ssh-argv.ts (the ONE policy — 2026-10-17 ruling). */
 function relaySsh(connection, extra, command) {
-	const args = [
-		"ssh",
+	return sshCommandArgv(connection, [
 		"-o",
 		"BatchMode=yes",
 		"-T",
@@ -961,14 +1170,7 @@ function relaySsh(connection, extra, command) {
 		"ServerAliveInterval=5",
 		"-o",
 		"ServerAliveCountMax=2"
-	];
-	if (connection.user !== void 0) args.push("-l", connection.user);
-	if (connection.port !== void 0) args.push("-p", String(connection.port));
-	if (connection.key !== void 0) args.push("-i", connection.key);
-	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
-	args.push(...extra, "--", connection.host);
-	if (command !== void 0) args.push(command);
-	return args;
+	], extra, command);
 }
 async function freePorts(count) {
 	const servers = [];
@@ -1123,12 +1325,16 @@ async function forwardRoute(argv, source, destination, signal, options) {
 		return await removeRemoteTemp(destination.connection, temp, wrap) ? "released" : "unknown";
 	};
 	try {
+		signal.throwIfAborted();
+		const daemonState = await waitForDaemonReady(destinationChild, 5e3);
+		if (daemonState === "exited") throw new Error(`dual-SSH rsync destination daemon exited before serving${relayDetail(destinationChild, sourceHold)}`);
+		if (daemonState === "timeout") throw new Error(`dual-SSH rsync destination daemon never announced readiness${relayDetail(destinationChild, sourceHold)}`);
 		signal.throwIfAborted();
 		if (!await originPortOpen(originPort, 15e3)) throw new Error(`dual-SSH rsync destination daemon never became reachable${relayDetail(destinationChild, sourceHold)}`);
 		signal.throwIfAborted();
 		const runArgv = relaySsh(source.connection, [], rsyncClientCommand(argv, source.path, sourcePort));
 		const result = await runNative(wrap(runArgv), signal);
-		if (result.exit === 255) result.stderr = (result.stderr + relayDetail(destinationChild, sourceHold)).slice(-OUTPUT_LIMIT);
+		if (result.exit !== 0) result.stderr = (result.stderr + relayDetail(destinationChild, sourceHold)).slice(-OUTPUT_LIMIT);
 		if (result.exit !== 0 && /remote port forwarding failed|administratively prohibited|could not request (local|remote) forwarding/.test(relayDetail(destinationChild, sourceHold))) throw new Error(`dual-SSH rsync forwarding route refused by an endpoint: ${relayDetail(destinationChild, sourceHold)}`);
 		return {
 			...result,
@@ -1153,6 +1359,19 @@ async function forwardRoute(argv, source, destination, signal, options) {
 		await Promise.allSettled([destinationChild.stop(), sourceHold.stop()]);
 	}
 }
+/** Wait until the destination daemon script announces itself (stderr marker,
+*  printed after its directory check and right before the daemon exec) or exits.
+*  'ready' only when the daemon is actually about to serve — closes the 0.3.1-e
+*  race where -L opens at session start but the script dies ~150ms later. */
+async function waitForDaemonReady(held, budgetMs) {
+	const deadline = Date.now() + budgetMs;
+	for (;;) {
+		if (/^SUPERD-RSYNC-TMP \S+$/m.test(held.stderrSink.text)) return "ready";
+		if (held.child.exitCode !== null) return "exited";
+		if (Date.now() >= deadline) return "timeout";
+		await new Promise((resolve$1) => setTimeout(resolve$1, 50));
+	}
+}
 function relayDetail(...held) {
 	const detail = held.map((child) => child.stderrSink.text).filter(Boolean).join("\n");
 	return detail ? `\n[relay stderr]\n${detail}` : "";
@@ -1234,14 +1453,7 @@ async function runRsync(request, source, destination, signal, options = {}) {
 	checkAbsolute(destination.path);
 	const argv = checkArgv("argv", request.argv);
 	if ("pullArgv" in request || "pushArgv" in request) throw new Error("remote: rsync takes argv only; pullArgv/pushArgv are copy-only fields");
-	for (const legacy of [
-		"dryRun",
-		"delete",
-		"excludes",
-		"preserve",
-		"verify",
-		"mkdir"
-	]) if (legacy in request) throw new Error(`remote: rsync field "${legacy}" was removed — pass native options through argv instead (e.g. "--dry-run", "--delete", "--exclude=<pattern>", "-a"/"-r"; verify/mkdir belong to the copy Hub/local lane)`);
+	for (const key of Object.keys(request)) if (key !== "src" && key !== "dst" && key !== "argv") throw new Error(`remote: rsync rejects unknown field "${key}" — native options go through argv (verify is a copy Hub-lane option; mkdir is copy-only; for destination parents pass --mkpath yourself)`);
 	if (!source.connection && !destination.connection) throw new Error("rsync requires at least one SSH endpoint; local-only is unsupported");
 	let result;
 	let route;
@@ -1289,6 +1501,9 @@ async function runRsync(request, source, destination, signal, options = {}) {
 		dst: request.dst,
 		argv,
 		route,
+		verification: "native-exit-only",
+		ok: result.exit === 0,
+		...result.exit === 0 ? {} : { reason: signal.aborted ? "aborted" : "non-zero-exit" },
 		command: `rsync ${argv.join(" ")}`,
 		...itemized.length > 0 || argv.includes("--itemize-changes") || argv.includes("-i") ? { itemizedChanges: itemized } : {},
 		...literalBytes === void 0 ? {} : { literalBytes },
@@ -1303,21 +1518,14 @@ async function runRsync(request, source, destination, signal, options = {}) {
 * placeholder host rsync appends and execs the canonical SSH argv. All tokens
 * are tool-built argv (identity options/aliases), never model text. */
 function rsyncRsh(connection, wrap) {
-	const args = [
-		"ssh",
-		"-o",
-		"BatchMode=yes",
-		"-T"
-	];
-	if (connection.user !== void 0) args.push("-l", connection.user);
-	if (connection.port !== void 0) args.push("-p", String(connection.port));
-	if (connection.key !== void 0) args.push("-i", connection.key);
-	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
-	args.push("--", connection.host);
 	return [
 		"bash",
 		"-c",
-		`shift; exec ${wrap(args).map(rshQuote).join(" ")} "$@"`,
+		`shift; exec ${wrap(sshCommandArgv(connection, [
+			"-o",
+			"BatchMode=yes",
+			"-T"
+		], [])).map(rshQuote).join(" ")} "$@"`,
 		"rsync-rsh"
 	].map(rshQuote).join(" ");
 }
@@ -1336,7 +1544,7 @@ function parseFileEndpoint(value) {
 	if (split < 1) throw new Error("file endpoint must be [target:]absolute/path");
 	const target = value.slice(0, split), path$1 = value.slice(split + 1);
 	checkAbsolute(path$1);
-	if (target.startsWith("byop:")) throw new Error("BYO-PTY has no binary file lane; select SSH/Docker/Incus/Hub");
+	if (target.startsWith("pty:")) throw new Error("a PTY session is not a filesystem endpoint; select SSH/Docker/Incus/Hub");
 	return {
 		target,
 		path: path$1
@@ -1345,13 +1553,9 @@ function parseFileEndpoint(value) {
 
 //#endregion
 //#region src/remote/ssh-targets.ts
-const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const USER = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
 const HOST = /^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?(?:[A-Za-z0-9_][A-Za-z0-9_.-]*|\[[A-Fa-f0-9:.]+\]|[A-Fa-f0-9:]+)$/;
 const JUMP = /^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?(?:[A-Za-z0-9_][A-Za-z0-9_.-]*|\[[A-Fa-f0-9:.]+\])(?::([0-9]+))?$/;
-function validateSshLabel(label) {
-	if (!LABEL.test(label)) throw new Error("[E_BAD_LABEL] remote: BYO-SSH label must use letters, digits, dot, underscore or hyphen and start with a letter/digit");
-}
 function bad(field) {
 	throw new Error(`[E_SSH_PARAMS] remote: invalid SSH ${field} — use host/user/port, an existing origin key file path, and optional ProxyJump aliases or [user@]host[:port] hops; no inline keys or shell options`);
 }
@@ -1391,48 +1595,20 @@ function normalizeSshConnection(input) {
 		...input.proxyJump === void 0 ? {} : { proxyJump: input.proxyJump }
 	});
 }
-/** One instance per Agent-owned driver; destroyed with its Agent/plugin owners. */
-var SshTargets = class {
-	targets = /* @__PURE__ */ new Map();
-	register(label, connection) {
-		validateSshLabel(label);
-		const normalized = normalizeSshConnection(connection), existing = this.targets.get(label);
-		if (existing && JSON.stringify(existing) !== JSON.stringify(normalized)) throw new Error(`[E_LABEL_CONFLICT] remote: byossh:${label} SSH identity conflict — nothing was run. Reuse the label without ssh, or choose another label; existing credentials were not replaced`);
-		if (!existing) this.targets.set(label, normalized);
-		return existing ?? normalized;
-	}
-	get(label) {
-		validateSshLabel(label);
-		return this.targets.get(label);
-	}
-	entries() {
-		return [...this.targets.entries()];
-	}
-	clear() {
-		this.targets.clear();
-	}
-};
 /** Shared by execution, probes and file/relay consumers. extraArgs is trusted
-* internal SSH argv (e.g. forwarding), never a model-provided shell string. */
+* internal SSH argv (e.g. forwarding), never a model-provided shell string.
+* Identity assembly lives in ssh-argv.ts (the ONE policy — 2026-10-17 ruling);
+* this wrapper only picks the tty/batch dialect base. */
 function sshArgv(connection, options = {}) {
-	const args = options.tty ? [
-		"ssh",
+	return sshCommandArgv(connection, options.tty ? [
 		"-tt",
 		"-o",
 		"BatchMode=yes"
 	] : [
-		"ssh",
 		"-o",
 		"BatchMode=yes",
 		"-T"
-	];
-	if (connection.user !== void 0) args.push("-l", connection.user);
-	if (connection.port !== void 0) args.push("-p", String(connection.port));
-	if (connection.key !== void 0) args.push("-i", connection.key);
-	if (connection.proxyJump !== void 0) args.push("-J", connection.proxyJump);
-	args.push(...options.extraArgs ?? [], "--", connection.host);
-	if (options.command !== void 0) args.push(options.command);
-	return args;
+	], options.extraArgs ?? [], options.command);
 }
 
 //#endregion
@@ -1440,17 +1616,17 @@ function sshArgv(connection, options = {}) {
 /** 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.script !== void 0) {
-		if (input.cmd !== void 0 || input.stdin !== void 0 || input.mode === "pty" || input.spawn !== void 0 || input.target?.startsWith("byop:")) throw new Error("[E_SCRIPT_PARAMS] remote: script is oneshot-only and cannot be combined with cmd, stdin, spawn or BYO-PTY");
-		if (typeof input.script !== "string" || !isAbsolute(input.script) || input.script.includes("\0")) throw new Error("[E_SCRIPT_PATH] remote: script must be a local absolute path without NUL");
+	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) throw new Error("[E_PARAMS] remote: target is required; spawn requires a byop:<label> target");
-	if (input.script !== void 0) {
+	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.script, "utf8");
+			stdin = await readFile(input.scriptPath, "utf8");
 		} catch (error) {
-			throw new Error(`[E_SCRIPT_READ] remote: cannot read local script ${JSON.stringify(input.script)} — ${error instanceof Error ? error.message : String(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,
@@ -1489,6 +1665,96 @@ async function runOneShot(argv, opts = {}) {
 	};
 }
 
+//#endregion
+//#region src/remote/helper.ts
+/** Reads helper-bin/MANIFEST.json next to the compiled module (lib/remote in the npm
+* package, super-dsh/remote in the Super closure — same relative layout). Missing or
+* malformed assets ⇒ null ⇒ shim-only mode; never throws. */
+function helperAssets(baseDir) {
+	const dir = baseDir ?? join(dirname(fileURLToPath(import.meta.url)), "helper-bin");
+	try {
+		const manifest = JSON.parse(readFileSync(join(dir, "MANIFEST.json"), "utf8"));
+		if (manifest?.format !== 1 || typeof manifest.ver !== "string" || typeof manifest.protocol !== "number" || !manifest.targets || typeof manifest.targets !== "object") return null;
+		return {
+			dir,
+			manifest
+		};
+	} catch {
+		return null;
+	}
+}
+/** `uname -s`/`uname -m` → shipped target triple. Unknown combos ⇒ null (shim). */
+function archTriple(sys, machine, shipped) {
+	const s = sys.trim().toLowerCase(), m = machine.trim().toLowerCase();
+	const candidates = s === "linux" ? m === "x86_64" || m === "amd64" ? "x86_64-unknown-linux-musl" : m === "aarch64" || m === "arm64" ? "aarch64-unknown-linux-musl" : null : s === "darwin" ? m === "arm64" || m === "aarch64" ? "aarch64-apple-darwin" : null : null;
+	if (candidates === null) return null;
+	return shipped.has(candidates) ? candidates : null;
+}
+function planKey(plan) {
+	switch (plan.kind) {
+		case "ssh": {
+			const c = plan.connection;
+			const host = c?.host ?? plan.host;
+			return `ssh|${c?.user ? c.user + "@" : ""}${host}${c?.port ? ":" + c.port : ""}${c?.proxyJump ? "|" + c.proxyJump : ""}`;
+		}
+		case "docker": return `docker|${plan.container}`;
+		case "incus": return `incus|${plan.container}`;
+	}
+}
+const PROBE_RE = /^SUPERD-PROBE (\S+) (\S+)$/m;
+const READY_RE = /^SUPERD-READY (\S+)$/m;
+var HelperRegistry = class {
+	states = /* @__PURE__ */ new Map();
+	constructor(assets, exec, probeArgv, uploadArgv) {
+		this.assets = assets;
+		this.exec = exec;
+		this.probeArgv = probeArgv;
+		this.uploadArgv = uploadArgv;
+	}
+	/** Never throws: any bootstrap failure resolves null (sticky) and the caller stays on the shim. */
+	ensure(plan) {
+		if (plan.kind !== "ssh" && plan.kind !== "docker" && plan.kind !== "incus") return Promise.resolve(null);
+		const key = planKey(plan);
+		let entry = this.states.get(key);
+		if (entry === void 0) {
+			entry = this.bootstrap(plan).catch(() => null);
+			entry.catch(() => {});
+			this.states.set(key, entry);
+		}
+		return entry;
+	}
+	async bootstrap(plan) {
+		const { manifest } = this.assets;
+		const first = await this.exec(this.probeArgv(plan, this.assets), { timeoutSec: 15 });
+		const ready = this.parseReady(first.stdout, manifest.ver, manifest.protocol);
+		if (ready !== null) return ready;
+		const probe = PROBE_RE.exec(first.stdout);
+		if (probe === null || first.exit !== 90 && first.exit !== 0) return null;
+		const triple = archTriple(probe[1], probe[2], new Set(Object.keys(manifest.targets)));
+		if (triple === null) return null;
+		const target = manifest.targets[triple];
+		const binary = await readFile(join(this.assets.dir, triple, target.file));
+		if ((await this.exec(this.uploadArgv(plan, triple, target.file, this.assets), {
+			stdin: binary,
+			timeoutSec: 60
+		})).exit !== 0) return null;
+		const second = await this.exec(this.probeArgv(plan, this.assets), { timeoutSec: 15 });
+		return this.parseReady(second.stdout, manifest.ver, manifest.protocol);
+	}
+	parseReady(stdout, ver, protocol) {
+		const ready = READY_RE.exec(stdout);
+		const banner = /^SUPERD-RUN proto=(\d+) name=superd-run ver=(\S+) target=(\S+)/m.exec(stdout);
+		if (ready === null || banner === null) return null;
+		if (banner[1] !== String(protocol) || banner[2] !== ver) return null;
+		return {
+			binPath: ready[1],
+			triple: banner[3],
+			ver,
+			protocol
+		};
+	}
+};
+
 //#endregion
 //#region src/remote/transports.ts
 /** POSIX 单引号机械转义（唯一一层转义，spec §三"一层机械转义"）。 */
@@ -1536,12 +1802,15 @@ bash -lc ${shQuote(cmd)}`;
 		];
 	}
 }
-/** Persistent pty（Ruling 2）：ssh/incus 走宿主管道，docker 经 script(1) 托管宿主 PTY。 */
+/** Persistent pty（Ruling 2）：ssh/incus 走宿主管道，docker 经 script(1) 托管宿主 PTY。
+* ssh 基座常驻固定 keepalive（2026-10-19 裁决）：客户端自有、零对端依赖，控制消息
+* 不触碰 PTY 字节流；oneshot 短命连接不带。 */
 function buildPtyArgv(plan) {
 	switch (plan.kind) {
 		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, {
 			tty: true,
-			command: "bash"
+			command: "bash",
+			extraArgs: SSH_PERSISTENT_KEEPALIVE
 		});
 		case "docker": return [
 			"script",
@@ -1568,6 +1837,121 @@ function buildSpawnArgv(spawnCommand) {
 		"/dev/null"
 	];
 }
+/** Hub PTY（0.3.2-c；0.3.2-d F4 修正）：会话子进程 = 本地 `script` PTY 托管的 WS 字节泵
+*  （hub-pty-pump.mjs）。与 docker exec 的嵌套 PTY 同形，但泵是哑 node 子进程、不像
+*  `ssh -tt` / `docker exec -it` 那样作为前台子进程自己把本地 tty 置 raw——所以本地包装必须
+*  `stty raw`：canonical+ISIG 下 0x03 在本地变 SIGINT 杀泵、0x04 变 EOF 结束泵 stdin
+*  （F4：input ^C/^D 与 job_kill 会打死整条会话）。raw 只作用于本地半段；对端 script PTY
+*  保持 canonical，^C/^D 在对端产生 SIGINT/EOF 正是我们要的语义（字节原样过线，解释权在
+*  对端）。kill 链 session 组杀 → 泵死 → WS 关 → 对端组杀，双向自然闭合。连接事实走 wrapper
+*  内 env 赋值（cookie 不进 argv、不落 ps）。 */
+function buildHubPtyArgv(endpoint, assets) {
+	const node = assets.nodePath ?? process.execPath;
+	return [
+		"script",
+		"-qfec",
+		`stty raw -echo 2>/dev/null ; ${`export SUPERD_HUB_PTY_URL=${shQuote(endpoint.url)} SUPERD_HUB_PTY_COOKIE=${shQuote(endpoint.cookie)} SUPERD_HUB_PTY_WS=${shQuote(endpoint.wsPath)}`} ; exec ${shQuote(node)} ${shQuote(assets.pumpPath)}`,
+		"/dev/null"
+	];
+}
+/** superd-run helper argv (spec: docs/specs/remote-rescope §5). Probe and upload are single
+*  `sh -c` hops (busybox/alpine/darwin-safe); run/killgroup over ssh go through exactly one
+*  remote-shell parse, same discipline as buildOneShotArgv. */
+function buildHelperProbeArgv(plan, assets) {
+	const { ver, targets } = assets.manifest;
+	return helperShellArgv(plan, `${Object.entries(targets).map(([triple, t]) => `d="$HOME/.cache/superd/run/${triple}-${ver}"; [ -x "$d/${t.file}" ] && { echo "SUPERD-READY $d/${t.file}"; "$d/${t.file}" banner; exit 0; };`).join(" ")} echo "SUPERD-PROBE $(uname -s 2>/dev/null || echo unknown) $(uname -m 2>/dev/null || echo unknown)"; exit 90`);
+}
+function buildHelperUploadArgv(plan, triple, file, assets) {
+	const dir = `$HOME/.cache/superd/run/${triple}-${assets.manifest.ver}`;
+	return helperShellArgv(plan, `mkdir -p "${dir}" && cat > "${dir}/${file}.tmp" && chmod 0755 "${dir}/${file}.tmp" && mv -f "${dir}/${file}.tmp" "${dir}/${file}"`);
+}
+function buildHelperOneShotArgv(plan, binPath, options) {
+	const { tag, cmd } = options;
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `exec ${shQuote(binPath)} run --tag ${shQuote(tag)} -- bash -lc ${shQuote(cmd)}` });
+		case "docker": return [
+			"docker",
+			"exec",
+			"-i",
+			"--",
+			plan.container,
+			binPath,
+			"run",
+			"--tag",
+			tag,
+			"--",
+			"bash",
+			"-lc",
+			cmd
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			binPath,
+			"run",
+			"--tag",
+			tag,
+			"--",
+			"bash",
+			"-lc",
+			cmd
+		];
+	}
+}
+function buildHelperKillgroupArgv(plan, binPath, tag) {
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: `${shQuote(binPath)} killgroup --tag ${shQuote(tag)}` });
+		case "docker": return [
+			"docker",
+			"exec",
+			"--",
+			plan.container,
+			binPath,
+			"killgroup",
+			"--tag",
+			tag
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			binPath,
+			"killgroup",
+			"--tag",
+			tag
+		];
+	}
+}
+function helperShellArgv(plan, script) {
+	switch (plan.kind) {
+		case "ssh": return sshArgv(plan.connection ?? { host: plan.host }, { command: script });
+		case "docker": return [
+			"docker",
+			"exec",
+			"-i",
+			"--",
+			plan.container,
+			"sh",
+			"-c",
+			script
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			"sh",
+			"-c",
+			script
+		];
+	}
+}
 
 //#endregion
 //#region src/remote/nonce-framing.ts
@@ -1577,11 +1961,11 @@ function genNonce(bytes = 8) {
 }
 /** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
 function wrapPtyCommand(cmd, nonce) {
-	return `{\n${cmd}\n} ; printf '\\033]133;D;${nonce};%s;%s\\007' "$?" "$PWD"\n`;
+	return `{\n${cmd}\n} ; __superd_e=$? ; printf '\\033]133;E;${nonce};%s\\007' "$(env -0 | base64 | tr -d '\\n\\r')" ; printf '\\033]133;D;${nonce};%s;%s\\007' "$__superd_e" "$PWD" ; unset __superd_e\n`;
 }
 /** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
 function buildInitCommand(nonce) {
-	return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
+	return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;E;${nonce};%s\\007' "$(env -0 | base64 | tr -d '\\n\\r')" ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
 }
 const ANSI_RE = /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)?|\[[0-9;?]*[ -/]*[@-~]|[@-Z\\-_])/g;
 function stripAnsi(s) {
@@ -1610,6 +1994,7 @@ function tailWindow(text, cap, stats) {
 	};
 }
 const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/;
+const ENV_BODY_RE = /^([A-Za-z0-9+/=]*)\x07/;
 /**
 * 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
 * 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
@@ -1617,31 +2002,60 @@ const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/;
 */
 function createNonceFrameParser(nonce, events) {
 	const prefix = `\x1b]133;D;${nonce};`;
+	const prefixE = `\x1b]133;E;${nonce};`;
+	const prefixes = [prefix, prefixE];
 	let buf = "";
 	let done = false;
 	const emit = (raw) => {
 		const text = normalizePtyText(raw);
 		if (text.length > 0) events.onOutput?.(text);
 	};
+	/** 缓冲尾若是任一候选前缀的真前缀则扣留（D/E 共用）；flush() 放出残余。 */
 	const holdback = () => {
-		const max = Math.min(buf.length, prefix.length - 1);
-		for (let k = max; k > 0; k--) if (buf.endsWith(prefix.slice(0, k))) return k;
-		return 0;
+		let best = 0;
+		for (const p of prefixes) {
+			const max = Math.min(buf.length, p.length - 1);
+			for (let k = max; k > best; k--) if (buf.endsWith(p.slice(0, k))) {
+				best = k;
+				break;
+			}
+		}
+		return best;
 	};
+	/** 扫描最早出现的帧：E（env 侧信道）先于 D 下发；D = settle，帧后字节丢弃。 */
 	const consume = () => {
 		if (done) return;
-		const i = buf.indexOf(prefix);
-		if (i < 0) {
+		let idx = -1;
+		let isEnv = false;
+		for (const p of prefixes) {
+			const i = buf.indexOf(p);
+			if (i >= 0 && (idx === -1 || i < idx)) {
+				idx = i;
+				isEnv = p === prefixE;
+			}
+		}
+		if (idx < 0) {
 			const keep = holdback();
 			emit(buf.slice(0, buf.length - keep));
 			buf = buf.slice(buf.length - keep);
 			return;
 		}
-		emit(buf.slice(0, i));
-		const rest = buf.slice(i + prefix.length);
+		emit(buf.slice(0, idx));
+		const rest = buf.slice(idx + (isEnv ? prefixE.length : prefix.length));
+		if (isEnv) {
+			const m$1 = ENV_BODY_RE.exec(rest);
+			if (m$1 === null) {
+				buf = buf.slice(idx);
+				return;
+			}
+			if (m$1[1].length > 0) events.onEnv?.(m$1[1]);
+			buf = rest.slice(m$1[0].length);
+			consume();
+			return;
+		}
 		const m = FRAME_BODY_RE.exec(rest);
 		if (m === null) {
-			buf = buf.slice(i);
+			buf = buf.slice(idx);
 			return;
 		}
 		events.onFrame({
@@ -1662,33 +2076,90 @@ function createNonceFrameParser(nonce, events) {
 		}
 	};
 }
+/** E 帧 payload → name→value-hash（值不离开端点；hash 只为 changed 判定）。空/坏 payload → undefined。 */
+function decodeEnvSnapshot(b64) {
+	if (b64.length === 0) return void 0;
+	let text;
+	try {
+		text = Buffer.from(b64, "base64").toString("utf8");
+	} catch {
+		return;
+	}
+	const map = /* @__PURE__ */ new Map();
+	for (const entry of text.split("\0")) {
+		if (entry.length === 0) continue;
+		const eq = entry.indexOf("=");
+		const name$1 = eq === -1 ? entry : entry.slice(0, eq);
+		if (name$1.startsWith("__superd")) continue;
+		let h = 5381;
+		const value = eq === -1 ? "" : entry.slice(eq + 1);
+		for (let i = 0; i < value.length; i++) h = (h * 33 ^ value.charCodeAt(i)) >>> 0;
+		map.set(name$1, h);
+	}
+	return map.size > 0 ? map : void 0;
+}
+/** prev 未知（init 侧信道失败）时返回 undefined——不报告假 delta。 */
+function diffEnv(prev, next) {
+	if (prev === void 0) return void 0;
+	const added = [], changed = [], removed = [];
+	for (const [name$1, h] of next) if (!prev.has(name$1)) added.push(name$1);
+	else if (prev.get(name$1) !== h) changed.push(name$1);
+	for (const name$1 of prev.keys()) if (!next.has(name$1)) removed.push(name$1);
+	added.sort();
+	changed.sort();
+	removed.sort();
+	return {
+		added,
+		changed,
+		removed
+	};
+}
 
 //#endregion
 //#region src/remote/pty-session.ts
 /** spec §五.2 逐字。 */
 const RECONNECT_NOTICE = "[remote: session reconnected to fresh shell; cwd reset to default]";
-/** 池键 → 模型面名字：剥掉 agent 前缀与内部标记（`t:` → 裸 target；`p:` → `byop:<label>`）。
-*  这是**唯一**的 key→名字映射规则，roster 与错误面共用——错误面不得回吐内部键：
-*  2026-10-03 实测报告 F1，`E_SESSION_*` 曾把 `session-<uuid>|p:<label>` 整条吐给模型。 */
+/** 池键 → 模型面名字：剥掉 agent 前缀与内部标记（`p:` → `pty:<id>`）。
+* 这是**唯一**的 key→名字映射规则，roster 与错误面共用——错误面不得回吐内部键：
+* 2026-10-03 实测报告 F1，`E_SESSION_*` 曾把 `session-<uuid>|p:<label>` 整条吐给模型。 */
 function displayKey(key) {
 	const raw = key.includes("|") ? key.slice(key.indexOf("|") + 1) : key;
-	return raw.startsWith("t:") ? raw.slice(2) : raw.startsWith("p:") ? `byop:${raw.slice(2)}` : raw;
+	return raw.startsWith("p:") ? `pty:${raw.slice(2)}` : raw;
 }
+const LEDGER_MAX = 20;
+const summaryOf = (cmd) => {
+	const first = cmd.trim().split(/\r?\n/, 1)[0] ?? "";
+	return first.length > 72 ? `${first.slice(0, 71)}…` : first;
+};
 const DEFAULT_INIT_TIMEOUT_SEC = 30;
 const INTERRUPT_GRACE_MS = 3e3;
+/** F2（0.3.2-d）：\x03 触发 ISIG 时内核 flush 输入队列——130-marker 必须等 flush 完成
+* 再入队，否则首字节被吞（实测 'rintf' not found → 会话死）。 */
+const MARKER_SETTLE_MS = 80;
 /** pty 收集内存安全帽（Ruling P15，与 oneshot HARD_CAP 对齐）：模型面只见尾窗，保留尾部。 */
 const OUTPUT_HARD_CAP = 4e6;
 var PtySession = class {
 	proc = null;
 	state = "cold";
 	startPromise = null;
-	queue = Promise.resolve();
 	idleTimer = null;
 	onChunk = null;
 	deathWaiters = [];
 	diag = "";
 	inFlight = 0;
-	lastSettleAt = 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）。 */
+	idleSince = null;
+	/** 意外死亡后的回收定时器（R2）：ready 过的会话先留池供 reconnect，超时仍无人寻址则出池。 */
+	deathTimer = null;
+	lastCwdSeen = null;
 	/** 是否曾成功初始化（ready 过）。决定死亡语义：ready 过 → reconnect（留池）；从未 ready → 出池（见 start()）。 */
 	everReady = false;
 	disposal;
@@ -1700,7 +2171,39 @@ var PtySession = class {
 	get sessionState() {
 		return this.state;
 	}
-	/** 创建来源（spawn 原文）；仅 `byop:<label>` 会话有。 */
+	/** 池键（driver 的 ttl/inspect 用）。 */
+	get key() {
+		return this.opts.key;
+	}
+	/** 最近帧 cwd（card 面）；从未执行过 = null。 */
+	get lastCwd() {
+		return this.lastCwdSeen;
+	}
+	/** 占用前台的 detached job 的 commandId（无 = null；close 拒绝与 busy 文案共用）。 */
+	get detachedCommandId() {
+		return this.detachedJob?.commandId ?? null;
+	}
+	/** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId，账本如实记录两者）；运行中的命令同步携带（input 回执用）。 */
+	attachJob(commandId, jobId) {
+		const entry = [...this.ledger].reverse().find((e) => e.commandId === commandId);
+		if (entry !== void 0) entry.jobId = jobId;
+		if (this.activeCommand !== null && this.activeCommand.commandId === commandId) this.activeCommand.jobId = jobId;
+	}
+	/** Workbench 身份（§3）：id + 可选 label + connection + byo 标记。 */
+	get identity() {
+		return {
+			id: this.opts.id,
+			...this.opts.label !== void 0 ? { label: this.opts.label } : {},
+			connection: this.opts.connection,
+			byo: this.opts.byo === true,
+			builtOn: this.opts.builtOn === true
+		};
+	}
+	/** 账本快照（session card 面，只读）。 */
+	ledgerSnapshot() {
+		return this.ledger;
+	}
+	/** spawn 创建原文（仅 BYO 会话；v2 起仅存档，不参与复用判定）。 */
 	get origin() {
 		return this.opts.origin;
 	}
@@ -1709,93 +2212,226 @@ var PtySession = class {
 		return {
 			state: this.state,
 			busy: this.inFlight > 0,
-			idleMs: this.lastSettleAt > 0 ? Date.now() - this.lastSettleAt : null,
+			idleMs: this.idleSince === null ? null : Date.now() - this.idleSince,
 			pid: this.proc?.pid ?? null
 		};
 	}
-	/** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。 */
-	dispatch(cmd, dOpts = {}) {
+	/** 预热创建（创建形无 cmd）：真正拨号到 init 帧——「会话已就绪」必须是真的，
+	* 而且只有 ready 过才挂 idle 回收（cold 会话没有 timer，会永远占配额）。 */
+	async warm() {
+		await this.start();
+	}
+	/** 同一会话命令占位制（2026-10-25 interactive-stdin 轮）：dispatch 入口**同步**建立
+	* 命令占位（activeCommand + inFlight + 账本条目）——上一条命令仍在运行（同步等待 /
+	* 等输入 / detached job）时新 cmd 立即 E_SESSION_BUSY；原「纯同步并发排 FIFO」语义
+	* 废除（排队会让等输入的命令与补输入动作互相卡死，也给 busy 留下绕行窗口）。
+	* P4/P5：超时不杀命令而是 handoff 成 running job；background 立即回执；P8 显式
+	* interrupt 保留在 job.interrupt；死亡/冷态先重启（reconnect 语义不变）。 */
+	dispatch(cmd, dOpts) {
+		if (this.state === "disposed") return Promise.reject(/* @__PURE__ */ new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`));
+		if (this.activeCommand !== null) {
+			const handle = this.activeCommand.jobId ?? this.activeCommand.commandId;
+			return Promise.reject(/* @__PURE__ */ new Error(`[E_SESSION_BUSY] remote: pty session '${this.opts.id}' still runs a command (${this.activeCommand.commandId}) — 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`));
+		}
+		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++;
 		const attempt = async () => {
 			const started = Date.now();
 			const reconnected = this.state === "dead";
-			if (this.state !== "ready") await this.start();
-			if (this.state === "disposed") throw new Error(`[E_SESSION_DISPOSED] remote pty session '${displayKey(this.opts.key)}' was disposed before dispatch`);
-			this.inFlight++;
+			/** 占位撤销：命令从未真正启动（建连失败 / 建连中被 dispose）——释放 busy 与计数，
+			* 撤掉账本条目（与旧时序等价：条目原本在 start 成功之后才建立）。 */
+			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();
+			} catch (error) {
+				abandon();
+				throw error;
+			}
+			if (this.state === "disposed") {
+				abandon();
+				throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`);
+			}
 			return await new Promise((resolve$1) => {
 				const nonce = genNonce();
 				const ring = new Utf16TailRing(OUTPUT_HARD_CAP);
 				let interrupted = false;
 				let settled = false;
+				let jobSettled = false;
 				let interruptTimer;
 				let killTimer;
-				const deathWaiter = () => finish({
-					output: ring.text,
-					exit: null,
-					cwd: null,
-					timedOut: interrupted
-				});
+				let markerTimer;
+				let jobDone = null;
+				let envNext;
+				const detach = () => {
+					const job = {
+						commandId,
+						read: (fromByte) => ring.read(fromByte),
+						stats: () => ring.stats(),
+						interrupt: () => {
+							if (!jobSettled) twoStage();
+						},
+						done: new Promise((res) => {
+							jobDone = res;
+						})
+					};
+					this.detachedJob = job;
+					settled = true;
+					resolve$1({
+						output: ring.text,
+						outputStats: { stdout: ring.stats() },
+						exit: null,
+						cwd: null,
+						timedOut: false,
+						running: true,
+						job,
+						commandId,
+						reconnected,
+						durationMs: Date.now() - started
+					});
+					return job;
+				};
 				const cleanup = () => {
 					this.onChunk = null;
+					this.detachedJob = null;
+					this.activeCommand = null;
 					this.deathWaiters = this.deathWaiters.filter((w) => w !== deathWaiter);
 					if (interruptTimer !== void 0) clearTimeout(interruptTimer);
 					if (killTimer !== void 0) clearTimeout(killTimer);
+					if (markerTimer !== void 0) clearTimeout(markerTimer);
 				};
-				const finish = (r) => {
-					if (settled) return;
-					settled = true;
+				const settle = (r) => {
+					if (jobSettled) return;
+					jobSettled = true;
 					cleanup();
 					this.inFlight--;
-					this.lastSettleAt = Date.now();
+					this.idleSince = Date.now();
 					this.resetIdleTimer();
-					resolve$1({
+					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() },
-						reconnected,
-						durationMs: Date.now() - started
-					});
+						commandId,
+						...envDelta !== void 0 ? { envDelta } : {}
+					};
+					jobDone?.(full);
+					if (!settled) {
+						settled = true;
+						resolve$1({
+							...full,
+							reconnected,
+							durationMs: Date.now() - started
+						});
+					}
 				};
+				const deathWaiter = () => settle({
+					output: ring.text,
+					exit: null,
+					cwd: null,
+					timedOut: interrupted
+				});
 				const parser = createNonceFrameParser(nonce, {
 					onOutput: (t) => {
 						ring.push(t);
 					},
-					onFrame: ({ exit, cwd }) => finish({
+					onEnv: (b64) => {
+						const m = decodeEnvSnapshot(b64);
+						if (m !== void 0) envNext = m;
+					},
+					onFrame: ({ exit, cwd }) => settle({
 						output: ring.text,
 						exit,
 						cwd,
 						timedOut: interrupted
 					})
 				});
-				this.onChunk = (c) => parser.feed(c);
-				this.write(wrapPtyCommand(cmd, nonce));
-				if (dOpts.stdin !== void 0) this.write(dOpts.stdin);
-				interruptTimer = setTimeout(() => {
+				const twoStage = () => {
 					interrupted = true;
 					this.write("");
-					this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					markerTimer = setTimeout(() => {
+						this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					}, MARKER_SETTLE_MS);
 					killTimer = setTimeout(() => {
 						this.killTree();
 						this.markDead();
-						finish({
+						settle({
 							output: ring.text,
 							exit: null,
 							cwd: null,
 							timedOut: true
 						});
 					}, INTERRUPT_GRACE_MS);
-				}, dOpts.timeoutSec === void 0 ? 12e4 : dOpts.timeoutSec * 1e3);
+				};
+				this.onChunk = (c) => parser.feed(c);
+				this.write(wrapPtyCommand(cmd, nonce));
+				if (dOpts.stdin !== void 0) this.write(dOpts.stdin);
 				this.deathWaiters.push(deathWaiter);
+				if (dOpts.background === true) {
+					detach();
+					return;
+				}
+				interruptTimer = setTimeout(() => detach(), dOpts.timeoutSec === void 0 ? 12e4 : dOpts.timeoutSec * 1e3);
 			});
 		};
-		const run = this.queue.then(attempt, attempt);
-		this.queue = run.then(() => void 0, () => void 0);
-		return run;
+		return attempt();
+	}
+	/** §3.1（2026-10-25）interactive-stdin：向当前运行中的命令追加 stdin——只写既有通道
+	* 与身份，不新建命令、账本条目或输出游标；不重连、不重放（dead/disposed 明确拒绝）。
+	* 校验与写入全同步：多次 input 按调用顺序整段写入不交错；写入失败如实抛错（私有
+	* write() 的静默忽略不适用于回执语义）。stdin:"" 是零字节写入，不是 EOF。 */
+	input(options) {
+		const fail = (code, hint) => Promise.reject(/* @__PURE__ */ new Error(`${code} remote: ${hint}`));
+		if (this.state === "disposed") return fail("[E_SESSION_DISPOSED]", `pty session '${displayKey(this.opts.key)}' was disposed — input never reaches a disposed session`);
+		if (this.state === "dead") return fail("[E_SESSION_NOT_RUNNING]", `pty session '${displayKey(this.opts.key)}' died — input never reconnects or replays; start a new command (exec reconnects a fresh shell) and re-send only what is still needed`);
+		if (this.state === "starting") return fail("[E_SESSION_NOT_READY]", `pty session '${displayKey(this.opts.key)}' is still initializing — wait for the exec receipt, then input`);
+		const active = this.activeCommand;
+		if (active === null) return fail("[E_SESSION_NOT_RUNNING]", `pty session '${displayKey(this.opts.key)}' has no running command (state ${this.state}) — input writes into a command started by exec; it is never an implicit shell command`);
+		if (options.commandId !== void 0 && options.commandId !== active.commandId) return fail("[E_COMMAND_MISMATCH]", `commandId ${JSON.stringify(options.commandId)} does not match the running command ${active.commandId} — input aimed at an earlier prompt is never written to the next command`);
+		const stdin = this.proc?.stdin;
+		if (stdin?.writable !== true) return fail("[E_SESSION_WRITE_FAILED]", `pty session '${displayKey(this.opts.key)}' has no writable stdin channel (state ${this.state}) — follow the running command via job_output for its settled result`);
+		try {
+			stdin.write(options.stdin);
+		} catch (error) {
+			return fail("[E_SESSION_WRITE_FAILED]", `writing stdin to pty session '${displayKey(this.opts.key)}' failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return Promise.resolve({
+			session: displayKey(this.opts.key),
+			commandId: active.commandId,
+			...active.jobId !== void 0 ? { jobId: active.jobId } : {},
+			writtenBytes: Buffer$1.byteLength(options.stdin, "utf8")
+		});
 	}
 	/** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
 	dispose() {
 		if (this.disposal) return this.disposal;
 		this.clearIdleTimer();
+		this.clearDeathTimer();
 		this.state = "disposed";
 		this.startPromise = null;
+		this.detachedJob?.interrupt();
 		const proc = this.proc;
 		const close = this.procClose;
 		const group = this.reapGroup(proc?.pid, 1e3, close);
@@ -1806,7 +2442,7 @@ var PtySession = class {
 		]).then(() => {
 			if (this.proc === proc) this.proc = null;
 		});
-		this.write("exit\n");
+		if (this.detachedJob === null) this.write("exit\n");
 		this.opts.onDead?.();
 		return this.disposal;
 	}
@@ -1818,6 +2454,7 @@ var PtySession = class {
 	}
 	async start() {
 		if (this.state === "disposed") throw new Error(`[E_SESSION_DISPOSED] remote pty session '${displayKey(this.opts.key)}' was disposed — the pool replaces disposed sessions; this reference is stale`);
+		this.clearDeathTimer();
 		if (this.startPromise === null) {
 			this.state = "starting";
 			this.startPromise = this.doStart().catch((err) => {
@@ -1846,6 +2483,9 @@ var PtySession = class {
 		proc.stderr.setEncoding("utf8").on("data", (d) => {
 			this.diag = (this.diag + d).slice(-2e3);
 		});
+		proc.stdin.on("error", (err) => {
+			this.diag = (this.diag + `\n[remote: stdin write failed: ${err.message}]`).slice(-2e3);
+		});
 		this.procClose = new Promise((resolve$1) => {
 			proc.once("close", () => {
 				this.markDead();
@@ -1867,18 +2507,24 @@ var PtySession = class {
 				reject(/* @__PURE__ */ new Error(`[E_SESSION_DIED] remote pty session '${displayKey(this.opts.key)}' died before initializing` + (this.diag.length > 0 ? `; transport stderr tail: ${this.diag}` : "")));
 			};
 			this.deathWaiters.push(waiter);
-			const parser = createNonceFrameParser(initNonce, { onFrame: () => {
-				clearTimeout(timer);
-				this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
-				if (this.state === "disposed") {
-					reject(/* @__PURE__ */ new Error(`[E_SESSION_DISPOSED] remote pty session '${displayKey(this.opts.key)}' disposed during init`));
-					return;
+			const parser = createNonceFrameParser(initNonce, {
+				onEnv: (b64) => {
+					const m = decodeEnvSnapshot(b64);
+					if (m !== void 0) this.envBaseline = m;
+				},
+				onFrame: () => {
+					clearTimeout(timer);
+					this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
+					if (this.state === "disposed") {
+						reject(/* @__PURE__ */ new Error(`[E_SESSION_DISPOSED] remote pty session '${displayKey(this.opts.key)}' disposed during init`));
+						return;
+					}
+					this.everReady = true;
+					this.state = "ready";
+					this.resetIdleTimer();
+					resolve$1();
 				}
-				this.everReady = true;
-				this.state = "ready";
-				this.resetIdleTimer();
-				resolve$1();
-			} });
+			});
 			this.onChunk = (c) => parser.feed(c);
 			this.write(buildInitCommand(initNonce));
 		});
@@ -1893,6 +2539,7 @@ var PtySession = class {
 		this.state = "dead";
 		this.startPromise = null;
 		this.clearIdleTimer();
+		this.armDeathReaper();
 		const waiters = this.deathWaiters;
 		this.deathWaiters = [];
 		for (const w of waiters) w();
@@ -1900,7 +2547,14 @@ var PtySession = class {
 	resetIdleTimer() {
 		this.clearIdleTimer();
 		if (this.state === "disposed") return;
-		this.idleTimer = setTimeout(() => void this.dispose(), this.opts.idleTtlSec * 1e3);
+		this.idleSince = Date.now();
+		this.idleTimer = setTimeout(() => {
+			if (this.inFlight > 0) {
+				this.resetIdleTimer();
+				return;
+			}
+			this.dispose();
+		}, this.opts.idleTtlSec * 1e3);
 		this.idleTimer.unref();
 	}
 	clearIdleTimer() {
@@ -1909,6 +2563,22 @@ var PtySession = class {
 			this.idleTimer = null;
 		}
 	}
+	/** 意外死亡后的回收：留池只换取一次 reconnect 机会，不得超过一段 idle TTL（R2 复核 P0）。
+	* 否则死会话永久占 label + 永久计入 10 配额，Agent 再也开不出新会话。 */
+	armDeathReaper() {
+		this.clearDeathTimer();
+		if (!this.everReady || this.state !== "dead") return;
+		this.deathTimer = setTimeout(() => {
+			this.dispose();
+		}, this.opts.idleTtlSec * 1e3);
+		this.deathTimer.unref();
+	}
+	clearDeathTimer() {
+		if (this.deathTimer !== null) {
+			clearTimeout(this.deathTimer);
+			this.deathTimer = null;
+		}
+	}
 	killTree() {
 		const pid = this.proc?.pid;
 		this.proc = null;
@@ -1998,19 +2668,20 @@ var PtyPool = class {
 		const s = this.sessions.get(key);
 		return s === void 0 || s.sessionState === "disposed" ? void 0 : s;
 	}
-	getOrCreate(key, argv, origin) {
+	/** v2：创建一律新建（「同 label 同来源复用」废除——复用只走 get/get by id）；disposed 残留由这里替换。 */
+	create(opts) {
 		if (this.disposed) throw new Error("[E_REMOTE_DISPOSED] remote: the owning Agent or plugin PTY pool was disposed");
-		let s = this.sessions.get(key);
-		if (s === void 0 || s.sessionState === "disposed") {
-			s = new PtySession({
-				key,
-				argv,
-				origin,
-				...this.defaults,
-				onDead: () => this.sessions.delete(key)
-			});
-			this.sessions.set(key, s);
-		}
+		const existing = this.sessions.get(opts.key);
+		if (existing !== void 0 && existing.sessionState !== "disposed") throw new Error(`[E_INTERNAL] remote: pty pool key collision for ${opts.id}`);
+		const s = new PtySession({
+			...opts,
+			...this.defaults,
+			onDead: () => {
+				this.sessions.delete(opts.key);
+				opts.onDead?.();
+			}
+		});
+		this.sessions.set(opts.key, s);
 		return s;
 	}
 	disposeAll() {
@@ -2053,6 +2724,202 @@ function resolveTarget(target) {
 		host: raw
 	};
 }
+const TRANSPORTS = [
+	"ssh",
+	"docker",
+	"incus"
+];
+function parseTargetForm(target) {
+	if (target === void 0 || target.length === 0) return { form: "empty" };
+	if (target === "pty") return { form: "pty-selector" };
+	if (target.startsWith("pty:")) {
+		const rest = target.slice(4);
+		if (rest.length === 0 || rest.includes(":")) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — the pty selector takes exactly one id or label ("pty:p-1a2b", "pty:build")`);
+		return {
+			form: "pty-selector",
+			idOrLabel: rest
+		};
+	}
+	if (target === "ssh") return { form: "ssh-prefix" };
+	if (target === "docker" || target === "incus" || target === "hub") throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} is a transport prefix — pass ${target === "hub" ? "hub:<machine>" : `${target}:<name>`}`);
+	if (target.startsWith("hub:")) {
+		const segs = target.slice(4).split(":");
+		if (segs[0] === void 0 || segs[0].length === 0) throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — hub takes a machine id`);
+		if (segs.length === 1) return {
+			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]`);
+	}
+	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 {
+			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)`);
+	return {
+		form: "bare",
+		name: target
+	};
+}
+
+//#endregion
+//#region src/remote/labels.ts
+/** label 字符集（与 BYO ssh label 同源）；禁 `pty` 与会话 id 形态（防 selector 歧义）。 */
+const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PTY_ID_RE = /^pty-[a-z0-9]{4}$/;
+const RESERVED_LABELS = new Set(["pty"]);
+function validateLabel(label) {
+	if (!LABEL_RE.test(label)) throw new Error(`[E_BAD_LABEL] remote: label must match ${LABEL_RE.source} (got ${JSON.stringify(label)})`);
+	if (RESERVED_LABELS.has(label) || PTY_ID_RE.test(label)) throw new Error(`[E_BAD_LABEL] remote: ${JSON.stringify(label)} is reserved (session ids are auto-generated; pick a different label)`);
+}
+function describeEntry(e) {
+	switch (e.kind) {
+		case "ssh": return `ssh host ${e.name}`;
+		case "ssh-byo": return `a BYO ssh identity (${e.name})`;
+		case "docker": return `docker container ${e.container}`;
+		case "incus": return `incus container ${e.container}`;
+		case "hub": return `hub machine ${e.machine}`;
+		case "pty": return `pty session ${e.id}${e.label !== void 0 ? ` (label ${e.label})` : ""}`;
+	}
+}
+/** 机器身份键：同一实体重扫后名字保持稳定（按身份匹配，不按名字）。 */
+const machineId = (e) => e.kind === "ssh" ? `ssh:${e.host}` : e.kind === "docker" ? `docker:${e.container}` : e.kind === "incus" ? `incus:${e.container}` : e.kind === "hub" ? `hub:${e.machine}` : void 0;
+const ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+var LabelPool = class {
+	/** 每 agent session 一个注册表：name → entry（机器 + 认领，到达序）。 */
+	sessions = /* @__PURE__ */ new Map();
+	registry(agent) {
+		let reg = this.sessions.get(agent);
+		if (reg === void 0) {
+			reg = /* @__PURE__ */ new Map();
+			this.sessions.set(agent, reg);
+		}
+		return reg;
+	}
+	resolve(name$1, agent) {
+		return this.sessions.get(agent)?.get(name$1);
+	}
+	/** 显式认领（BYO ssh / PTY label）：任何已立名字占用即拒——名字是模型选的，不自动改名。 */
+	claim(name$1, agent, claim) {
+		const reg = this.registry(agent);
+		const existing = reg.get(name$1);
+		if (existing !== void 0) throw new Error(`[E_LABEL_IN_USE] remote: label ${JSON.stringify(name$1)} is already taken by ${describeEntry(existing)} — nothing was run.\n  To address it:   use the name directly (creation always claims a fresh name — spawn/ssh never adopt)\n` + (existing.kind === "pty" ? `  To free it:      close ${existing.id} ({action:"close", target:"pty:${existing.id}"}) — a session that died still holds its label until it is closed or reaped\n` : "") + `  To create new:   pick another label`);
+		reg.set(name$1, claim);
+	}
+	/** 生成不撞本 session 的 id（`pty-` PTY 会话 / `ssh-` BYO ssh 身份）。 */
+	freshId(prefix, agent) {
+		const reg = this.registry(agent);
+		for (;;) {
+			let id = prefix;
+			for (let i = 0; i < 4; i++) id += ID_ALPHABET[Math.floor(Math.random() * 36)];
+			if (!reg.has(id)) return id;
+		}
+	}
+	/**
+	* 现场采集 merge（roster / 裸名 miss 触发）：按 ssh → docker → incus → hub 顺序并入。
+	* 已立名字永不挪动：同一实体（身份键相同）保持原槽；新实体撞已立名字 = latecomer，
+	* 自动加 `<transport>-<name>`（再冲突 -2/-3）——无论对方是认领还是更早的机器。
+	* 本轮扫描里消失的机器出表（名字释放）；认领永远保留。
+	*/
+	mergeScan(agent, scan) {
+		const reg = this.registry(agent);
+		const renamed = [];
+		const present = /* @__PURE__ */ new Map();
+		for (const [name$1, e] of [...reg]) {
+			const id = machineId(e);
+			if (id === void 0) continue;
+			reg.delete(name$1);
+			present.set(id, e);
+		}
+		const place = (transport, raw, make) => {
+			const id = `${transport}:${raw}`;
+			const known = present.get(id);
+			if (known !== void 0) {
+				reg.set(known.name, known);
+				return;
+			}
+			const fresh = make(raw);
+			if (!reg.has(raw)) {
+				reg.set(raw, fresh);
+				return;
+			}
+			let candidate = `${transport}-${raw}`, n = 2;
+			while (reg.has(candidate)) candidate = `${transport}-${raw}-${n++}`;
+			reg.set(candidate, make(candidate));
+			renamed.push([fresh, candidate]);
+		};
+		for (const host of scan.sshHosts) place("ssh", host, (name$1) => ({
+			kind: "ssh",
+			name: name$1,
+			host
+		}));
+		for (const c of scan.docker) place("docker", c, (name$1) => ({
+			kind: "docker",
+			name: name$1,
+			container: c
+		}));
+		for (const c of scan.incus) place("incus", c, (name$1) => ({
+			kind: "incus",
+			name: name$1,
+			container: c
+		}));
+		for (const m of scan.hub) place("hub", m, (name$1) => ({
+			kind: "hub",
+			name: name$1,
+			machine: m
+		}));
+		return { renamed };
+	}
+	/** 认领释放（会话 dispose/TTL；BYO 身份随 session 存亡）；幂等。 */
+	release(name$1, agent) {
+		this.sessions.get(agent)?.delete(name$1);
+	}
+	/** roster 面：本 session 的全部条目（机器 + 认领，插入序）。 */
+	list(agent) {
+		return [...this.sessions.get(agent)?.values() ?? []];
+	}
+	/** driver dispose：全部 session 注册表清空。 */
+	clear() {
+		this.sessions.clear();
+	}
+};
 
 //#endregion
 //#region src/remote/status.ts
@@ -2128,21 +2995,11 @@ function renderProbe(p) {
 		case "container": return `probe: container ${p.status} (just now, on demand)`;
 	}
 }
-/**
-* 唯一偏离 brief 处：brief 的 renderSession 测试以不含 `pid` 的三字段字面量直呼本函数，而
-* SessionSnapshot.pid 为必填 → 按测试意图（会话层词汇只由 state/busy/idleMs 决定）收窄为
-* 结构子集；传完整 SessionSnapshot 仍然成立，运行时语义零变化。
-*/
-function renderSession(s) {
-	if (s === void 0 || s.state === "cold" || s.state === "starting" || s.state === "disposed") return "session: none — dials on first exec";
-	if (s.state === "dead") return "session: died — next exec cold-starts a fresh shell";
-	if (s.busy) return "session: busy (a command is running)";
-	return `session: idle ${Math.round((s.idleMs ?? 0) / 1e3)}s (connected)`;
-}
-/** PTY 会话状态行（BYO-PTY 面）：无会话 = 这个 label 下没有活会话，且**不会自建**——
-* 与 transport target 的 "dials on first exec" 是两回事，故不复用那句。 */
-function renderPtySession(s) {
-	return s === void 0 ? "session: none — no live PTY under this label" : renderSession(s);
+/** 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
@@ -2234,22 +3091,24 @@ function literalHosts(text) {
 		wildcardBlocks
 	};
 }
-/**
-* Build the roster text. Sections render independently; a failing section
-* renders its native error (honest vocabulary: never invent, never hide).
-*/
-async function renderRoster(sessions, opts = {}) {
+/** 三段本地扫描（各自独立降级，错误如实带回给 roster 呈现）。 */
+async function scanLocal(opts = {}) {
 	const runner = opts.runner ?? runOneShot;
 	const readSshConfig = opts.readSshConfig ?? (async () => await readFile(join(homedir(), ".ssh", "config"), "utf8"));
 	const hard = opts.hardTimeoutSec ?? 10;
-	const lines = [];
+	let ssh = {
+		hosts: [],
+		wildcardBlocks: 0
+	};
 	try {
-		const { hosts, wildcardBlocks } = literalHosts(await readSshConfig());
-		lines.push(`ssh hosts (~/.ssh/config): ${hosts.length > 0 ? hosts.join(", ") : "(none)"}${wildcardBlocks > 0 ? ` (+${wildcardBlocks} wildcard default blocks, not listed)` : ""}`);
+		ssh = literalHosts(await readSshConfig());
 	} catch (error) {
-		lines.push(`ssh hosts: no readable ~/.ssh/config (${error instanceof Error ? error.message : String(error)})`);
+		ssh = {
+			hosts: [],
+			wildcardBlocks: 0,
+			error: error instanceof Error ? error.message : String(error)
+		};
 	}
-	lines.push(`byossh labels (this Agent, in memory): ${opts.byosshLabels?.map((label) => `byossh:${label}`).join(", ") || "(none)"}`);
 	const docker = await runner([
 		"docker",
 		"ps",
@@ -2257,13 +3116,6 @@ async function renderRoster(sessions, opts = {}) {
 		"--format",
 		"{{.Names}}	{{.State}}"
 	], { timeoutSec: hard });
-	if (docker.exit === 0) {
-		const rows = docker.stdout.trim().split(/\r?\n/).filter(Boolean).map((l) => {
-			const [name$1, state] = l.split("	");
-			return `${name$1}${state !== void 0 && state !== "" ? ` (${state})` : ""}`;
-		});
-		lines.push(`docker containers: ${rows.length > 0 ? rows.join(", ") : "(none)"}`);
-	} else lines.push(`docker containers: unavailable — ${docker.timedOut ? `scan timed out after ${hard}s` : oneLine(docker.stderr) || `docker exited ${docker.exit}`}`);
 	const incus = await runner([
 		"incus",
 		"list",
@@ -2272,35 +3124,97 @@ async function renderRoster(sessions, opts = {}) {
 		"--columns",
 		"ns"
 	], { timeoutSec: hard });
-	if (incus.exit === 0) {
-		const rows = incus.stdout.trim().split(/\r?\n/).filter(Boolean).map((l) => {
+	return {
+		ssh,
+		docker: docker.exit === 0 ? { rows: docker.stdout.trim().split(/\r?\n/).filter(Boolean).map((l) => {
+			const [name$1, state] = l.split("	");
+			return {
+				name: (name$1 ?? "").trim(),
+				state: (state ?? "").trim()
+			};
+		}).filter((r) => r.name.length > 0) } : {
+			rows: [],
+			error: oneLine(docker.stderr) || `docker exited ${docker.exit}`,
+			...docker.timedOut ? { timedOut: true } : {}
+		},
+		incus: incus.exit === 0 ? { rows: incus.stdout.trim().split(/\r?\n/).filter(Boolean).map((l) => {
 			const [name$1, state] = l.split(",");
-			return `${name$1}${state !== void 0 && state !== "" ? ` (${state.trim()})` : ""}`;
-		});
-		lines.push(`incus containers: ${rows.length > 0 ? rows.join(", ") : "(none)"}`);
-	} else lines.push(`incus containers: unavailable — ${incus.timedOut ? `scan timed out after ${hard}s` : oneLine(incus.stderr) || `incus exited ${incus.exit}`}`);
-	lines.push(sessions.length > 0 ? `live pty sessions: ${sessions.map((s) => `${s.target} [${s.state}${s.idleSec !== null ? `, idle ${s.idleSec}s` : ""}]`).join(", ")}` : "live pty sessions: none");
+			return {
+				name: (name$1 ?? "").trim(),
+				state: (state ?? "").trim()
+			};
+		}).filter((r) => r.name.length > 0) } : {
+			rows: [],
+			error: oneLine(incus.stderr) || `incus exited ${incus.exit}`,
+			...incus.timedOut ? { timedOut: true } : {}
+		}
+	};
+}
+/** 统一池视图的 roster 呈现：机器三段 + BYO ssh 同位（built on）+ pty 会话段（caller-scoped）。 */
+function renderRoster(scan, entries, sessions, hubTargets) {
+	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})`);
+	else {
+		const sshNames = entries.filter((e) => e.kind === "ssh").map((e) => e.name);
+		const byoNames = entries.filter((e) => e.kind === "ssh-byo").map((e) => `${e.name} (built on)`);
+		const all = [...sshNames, ...byoNames];
+		lines.push(`ssh hosts (~/.ssh/config + registered): ${all.length > 0 ? all.join(", ") : "(none)"}${scan.ssh.wildcardBlocks > 0 ? ` (+${scan.ssh.wildcardBlocks} wildcard default blocks, not listed)` : ""}`);
+	}
+	const dockerStates = new Map(scan.docker.rows.map((r) => [r.name, r.state]));
+	const dockerEntries = entries.filter((e) => e.kind === "docker");
+	if (scan.docker.error !== void 0) lines.push(`docker containers: unavailable — ${scan.docker.timedOut ? `scan timed out` : scan.docker.error}`);
+	else lines.push(`docker containers: ${dockerEntries.length > 0 ? dockerEntries.map((e) => e.kind === "docker" && `${e.name}${e.name !== e.container ? ` (= docker:${e.container}${dockerStates.get(e.container) ? `, ${dockerStates.get(e.container)}` : ""})` : dockerStates.get(e.container) !== void 0 && dockerStates.get(e.container) !== "" ? ` (${dockerStates.get(e.container)})` : ""}`).join(", ") : "(none)"}`);
+	const incusStates = new Map(scan.incus.rows.map((r) => [r.name, r.state]));
+	const incusEntries = entries.filter((e) => e.kind === "incus");
+	if (scan.incus.error !== void 0) lines.push(`incus containers: unavailable — ${scan.incus.timedOut ? `scan timed out` : scan.incus.error}`);
+	else lines.push(`incus containers: ${incusEntries.length > 0 ? incusEntries.map((e) => e.kind === "incus" && `${e.name}${e.name !== e.container ? ` (= incus:${e.container}${incusStates.get(e.container) ? `, ${incusStates.get(e.container)}` : ""})` : incusStates.get(e.container) !== void 0 && incusStates.get(e.container) !== "" ? ` (${incusStates.get(e.container)})` : ""}`).join(", ") : "(none)"}`);
+	lines.push(sessions.length > 0 ? `pty sessions: ${sessions.map((s) => {
+		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}]`;
+	}).join(" · ")}` : "pty sessions: none");
 	return lines.join("\n");
 }
 
 //#endregion
 //#region src/remote/driver.ts
-/** PTY label 字符集：只禁空白 / `:` / 控制字符（roster 一行一 label，带换行的 label 渲染即烂）。 */
-const PTY_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-/** 双轨调度器（spec §七 Phase 2）：参数校验 → 路由 → oneshot 子进程 / pty 会话池。 */
+/** 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;
+/** hub 线 one-shot 监督披露（0.3.2-c）：对端 = 我们自己的 hub server（bash -lc 于独立进程组，
+*  Node 原生 TERM→2s→KILL + 输出环 + 租约生命周期）；superd-run helper 是 dumb-pipe 专用物，
+*  从不经 hub 上传（non-goal，docs/10_plans/2026-10-25-hub-remote-parity.md §3 O1/O8）。 */
+const HUB_RUNNER = "hub-lease (peer bash -lc, peer Node supervision)";
+/** hub PTY 泵资产：pump 与本模块同目录（npm 包与 Super 闭包同构，helper.ts 同款纪律）。
+*  ws 模块路径由 transport 侧（superd-hub 上下文，分叉的 proven 解析链）解析后经
+*  ptyEndpoint 传入——闭包自身子树无可解析的 ws，按名解析不在闭包里做（0.3.2-c 定稿）。 */
+function hubPtyAssets() {
+	return { pumpPath: join(dirname(fileURLToPath(import.meta.url)), "hub-pty-pump.mjs") };
+}
+/** 账本键与 jobId 同构（同格式 `<kind>-<16hex>`）；background 通道预传入 registry id 时两者字面相等。 */
+const genCommandId = () => `remote-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+/** 双轨调度器：参数校验 → 目标语法（parseTargetForm）→ 统一 label 池 → oneshot 子进程 / pty 会话池。 */
 var RemoteDriver = class {
-	sshTargets = new SshTargets();
 	pool;
+	labels = new LabelPool();
 	hubOwner = randomUUID();
 	hubProviders = /* @__PURE__ */ new Set();
 	processes = /* @__PURE__ */ new Set();
 	starting = /* @__PURE__ */ new Set();
 	fileAbort = new AbortController();
 	disposed = false;
+	/** undefined = 未尝试；null = 资产缺失（shim-only）；registry = 每 target sticky 状态机。 */
+	helpers;
+	runnerOf = /* @__PURE__ */ new WeakMap();
 	disposal;
+	ptyIdleTtlSec;
 	constructor(opts = {}) {
 		this.opts = opts;
-		this.pool = new PtyPool({ idleTtlSec: opts.idleTtlSec ?? 600 });
+		this.ptyIdleTtlSec = opts.idleTtlSec ?? REMOTE_PTY_IDLE_TTL_SEC;
+		this.pool = new PtyPool({ idleTtlSec: this.ptyIdleTtlSec });
 	}
 	async call(params, callCtx = {}) {
 		const started = Date.now();
@@ -2308,10 +3222,11 @@ var RemoteDriver = class {
 			this.assertOpen();
 			const prepared = await prepareRemoteInput(params);
 			this.assertOpen();
-			const routing = this.route(prepared);
-			const result = await this.execute(prepared, routing, callCtx);
+			const form = parseTargetForm(prepared.target);
+			this.validate(form, prepared);
+			const result = await this.execute(prepared, form, callCtx);
 			this.audit({
-				target: routing.display,
+				target: result.target,
 				cmd: prepared.cmd,
 				cwd: result.cwd ?? void 0,
 				exit: result.exit,
@@ -2328,10 +3243,107 @@ var RemoteDriver = class {
 			throw error;
 		}
 	}
-	/** Native-first copy routing (spec: remote-native-shortcut): CLI peers run
-	* their native CLI verbatim; only Hub↔local↔local stays on the staged tree
-	* lane with verify/mkdir. Mixed pairs (Hub↔CLI peer) are refused: Hub has no
-	* native CLI and the tree lane has no CLI options. */
+	/** 参数互斥矩阵（§2）：spawn/ssh 是 BYO 入口（参数在场即 BYO），只与对应形态的 target 配对。 */
+	validate(form, params) {
+		if (params.timeout !== void 0 && (!Number.isFinite(params.timeout) || params.timeout <= 0)) throw new Error(`[E_BAD_TIMEOUT] remote: timeout must be a positive number of seconds (got ${JSON.stringify(params.timeout)})`);
+		if (params.stdin !== void 0 && (params.cmd === void 0 || params.cmd.length === 0)) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd");
+		const hasSpawn = params.spawn !== void 0 && params.spawn.length > 0;
+		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";
+		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)");
+	}
+	async execute(params, form, callCtx) {
+		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
+		const cap = this.opts.maxOutputChars ?? 3e4;
+		const sessionKey = callCtx.sessionKey ?? "no-session";
+		const hasCmd = params.cmd !== void 0 && params.cmd.length > 0;
+		params.spawn !== void 0 && params.spawn.length;
+		if (form.form === "hub") {
+			const hub = this.requireHub();
+			this.hubProviders.add(hub);
+			const process$1 = this.own(await hub.start(form.machine, {
+				...params,
+				target: `hub:${form.machine}`,
+				mode: "oneshot",
+				timeout: timeoutSec
+			}, this.hubOwner));
+			if (this.disposed) process$1.cancel("owner disposed");
+			const result = await process$1.done;
+			const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
+			const out = tailWindow(stdout.text, cap, stdout.stats);
+			const err = tailWindow(stderr.text, cap, stderr.stats);
+			return {
+				...result,
+				mode: "oneshot",
+				target: `hub:${form.machine}`,
+				connection: `hub:${form.machine}`,
+				cwd: null,
+				reconnected: false,
+				runner: HUB_RUNNER,
+				stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out.text,
+				stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
+				...out.stats ? { outputStats: {
+					stdout: out.stats,
+					stderr: err.stats
+				} } : { outputStatsUnavailable: true },
+				...out.truncated === void 0 ? {} : { truncated: out.truncated }
+			};
+		}
+		const lane = this.createPtyLane(params, form, sessionKey);
+		if (lane !== void 0) {
+			const session = lane.session;
+			if (!hasCmd) {
+				await session.warm();
+				return this.warmReceipt(session);
+			}
+			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+		}
+		if (params.ssh !== void 0) {
+			const label = form.form === "direct" || form.form === "bare" ? form.name : void 0;
+			const name$1 = this.registerByoSsh(label, params.ssh, sessionKey);
+			if (!hasCmd) return {
+				mode: "oneshot",
+				target: `ssh:${name$1}`,
+				connection: `ssh:${name$1}`,
+				byoTag: "byo-ssh",
+				exit: null,
+				cwd: null,
+				timedOut: false,
+				reconnected: false,
+				stdout: `ssh:${name$1} registered (byo-ssh, no dialing). Reuse the label anywhere ssh: aliases work; a new Agent registers again.`,
+				durationMs: 0
+			};
+			return await this.oneshot({
+				kind: "ssh",
+				host: normalizeSshConnection(params.ssh).host,
+				connection: normalizeSshConnection(params.ssh)
+			}, `ssh:${name$1}`, params, timeoutSec, cap);
+		}
+		if (form.form === "pty-selector" && form.idOrLabel === void 0) throw new Error("[E_PARAMS] remote: \"pty\" alone selects nothing — append an id/label (pty:pty-1a2b, pty:build) or pass spawn to create one");
+		if (form.form === "pty-selector") {
+			const session = this.resolvePty(form.idOrLabel, sessionKey);
+			if (!hasCmd) return this.cardReceipt(session);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+		}
+		if (form.form === "direct") {
+			const plan$1 = form.transport === "ssh" ? this.sshPlanFor(form.name, sessionKey) : resolveTarget(`${form.transport}:${form.name}`);
+			return await this.oneshot(plan$1, `${form.transport}:${form.name}`, params, timeoutSec, cap);
+		}
+		if (form.form !== "bare") throw new Error("[E_INTERNAL] remote: unreachable target form after routing");
+		const entry = await this.resolvePoolEntry(form.name, sessionKey);
+		if (entry.kind === "pty") {
+			const session = this.resolvePty(form.name, sessionKey);
+			if (!hasCmd) return this.cardReceipt(session);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+		}
+		if (entry.kind === "hub") return await this.hubOneshot(entry.machine, `hub:${entry.machine}`, params, timeoutSec, cap);
+		const plan = this.planOf(entry);
+		return await this.oneshot(plan, form.name, params, timeoutSec, cap);
+	}
+	/** Native-first copy routing (spec: remote-native-shortcut) — unchanged by the workbench round. */
 	copy(request, signal, callCtx = {}) {
 		const combined = AbortSignal.any([signal, this.fileAbort.signal]);
 		const work = (async () => {
@@ -2403,13 +3415,18 @@ var RemoteDriver = class {
 				path: dst.path,
 				endpoint: localFileEndpoint()
 			}, combined);
-			if (request.verify !== void 0 || request.mkdir !== void 0) throw new Error("copy: verify/mkdir apply to the Hub/local staged lane only; native CLI routes do not verify or create parents (mirror the CLI's own behavior with argv like -r)");
+			if (request.verify !== void 0) throw new Error("copy: verify is a Hub/local staged lane option (independent SHA-256); native routes report exit-code-only verification — self-verify via oneshot digest commands when needed");
 			const planOf = (end) => end.kind === "cli" ? end.plan : end.kind === "local" ? { kind: "local" } : void 0;
 			const srcPlan = planOf(src), dstPlan = planOf(dst);
 			if (srcPlan === void 0 || dstPlan === void 0) throw new Error("copy: unreachable route resolution");
+			const execArgvFor = (plan, script) => {
+				const argv = helperShellArgv(plan, script);
+				return this.opts.nativeArgvFor ? this.opts.nativeArgvFor(argv) : argv;
+			};
 			return nativeCopy({
 				src: request.src,
 				dst: request.dst,
+				...request.mkdir === void 0 ? {} : { mkdir: request.mkdir },
 				...request.argv === void 0 ? {} : { argv: request.argv },
 				...request.pullArgv === void 0 ? {} : { pullArgv: request.pullArgv },
 				...request.pushArgv === void 0 ? {} : { pushArgv: request.pushArgv }
@@ -2422,7 +3439,10 @@ var RemoteDriver = class {
 					plan: dstPlan,
 					path: dst.path
 				}
-			}, combined, { wrapArgv: this.opts.nativeArgvFor });
+			}, combined, {
+				wrapArgv: this.opts.nativeArgvFor,
+				execArgvFor
+			});
 		})();
 		this.starting.add(work);
 		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
@@ -2436,7 +3456,8 @@ var RemoteDriver = class {
 			const endpoint = async (value) => {
 				const parsed = parseFileEndpoint(value);
 				if (!parsed.target) return { path: parsed.path };
-				if (/^(hub|docker|incus|byop):/.test(parsed.target)) throw new Error("rsync supports SSH/byossh only (plus one local endpoint); no mixed-transport or copy fallback");
+				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");
 				const plan = await this.resolveConnectionTarget(parsed.target, callCtx);
 				this.assertOpen();
 				combined.throwIfAborted();
@@ -2456,45 +3477,66 @@ var RemoteDriver = class {
 		return work;
 	}
 	/** Only called from JobSpec.run: admission precedes local file reads and discovery. */
-	start(input, signal) {
-		const work = this.startPrepared(input, AbortSignal.any([signal, this.fileAbort.signal]));
+	start(input, signal, callCtx = {}) {
+		const work = this.startPrepared(input, AbortSignal.any([signal, this.fileAbort.signal]), callCtx);
 		this.starting.add(work);
 		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
 		return work;
 	}
-	async startPrepared(input, signal) {
+	async startPrepared(input, signal, callCtx = {}) {
 		this.assertOpen();
 		signal.throwIfAborted();
 		const params = await prepareRemoteInput(input);
 		this.assertOpen();
 		signal.throwIfAborted();
-		const route = this.route(params);
-		if (route.mode !== "oneshot" || route.pty) throw new Error("remote: background requires oneshot");
+		const form = parseTargetForm(params.target);
+		this.validate(form, params);
+		if (form.form !== "direct" && form.form !== "bare" && form.form !== "hub") throw new Error("remote: background oneshot takes a machine target; PTY lanes go through the pty job channel");
+		if (params.ssh !== void 0 && (form.form === "direct" || form.form === "bare") && form.transport !== "docker" && form.transport !== "incus") this.registerByoSsh(form.name, params.ssh, callCtx.sessionKey ?? "no-session");
 		let process$1;
-		if (route.display.startsWith("hub:")) {
-			const hub = this.requireHub();
-			this.hubProviders.add(hub);
-			process$1 = await hub.start(route.display.slice(4), {
-				...params,
-				mode: "oneshot"
-			}, this.hubOwner);
-		} else {
-			const plan = route.plan ?? await this.resolveBareName(route.bare, "no-session", false);
+		if (form.form === "hub") process$1 = await this.hubOneshotProcess(form.machine, params);
+		else if (form.form === "direct") {
+			const plan = form.transport === "ssh" ? this.sshPlanFor(form.name, callCtx.sessionKey ?? "no-session") : resolveTarget(`${form.transport}:${form.name}`);
 			this.assertOpen();
 			signal.throwIfAborted();
-			if (plan.kind === "pty") throw new Error("remote: background requires oneshot");
 			process$1 = await this.nativeProcess(plan, 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);
+		} 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;
 	}
-	nativeProcess(plan, params, timeoutSec, signal = this.fileAbort.signal) {
+	async nativeProcess(plan, params, timeoutSec, signal = this.fileAbort.signal) {
 		const cleanupTag = randomUUID().slice(0, 8);
+		const helper = await this.ensureHelper(plan);
+		if (helper !== null && !this.disposed) {
+			const process$2 = startOneShot(buildHelperOneShotArgv(plan, helper.binPath, {
+				tag: cleanupTag,
+				cmd: params.cmd
+			}), {
+				stdin: params.stdin,
+				timeoutSec
+			});
+			this.runnerOf.set(process$2, `superd-run ${helper.ver} (${helper.triple})`);
+			process$2.done.then((result) => {
+				if (!result.cancelled && !result.timedOut) return;
+				startOneShot(buildHelperKillgroupArgv(plan, helper.binPath, cleanupTag), { timeoutSec: 15 }).done.catch(() => {});
+			}).catch(() => {});
+			const tracked = Promise.resolve(process$2);
+			this.starting.add(tracked);
+			tracked.then(() => this.starting.delete(tracked), () => this.starting.delete(tracked));
+			return tracked;
+		}
 		const process$1 = startOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(plan, params.cmd, { cleanupTag }), {
 			stdin: params.stdin,
 			timeoutSec
 		});
+		this.runnerOf.set(process$1, "posix-shim");
 		process$1.done.then((result) => {
 			if (!result.cancelled && !result.timedOut) return;
 			const pidfile = `"\${TMPDIR:-/tmp}/superd-oneshot-${cleanupTag}.pgid"`;
@@ -2506,296 +3548,395 @@ var RemoteDriver = class {
 		work.then(() => this.starting.delete(work), () => this.starting.delete(work));
 		return work;
 	}
+	/** Helper bootstrap is best-effort and sticky: any failure parks null for this driver
+	* lifetime and the shim stays the path. First call to a target pays probe (+ upload). */
+	async ensureHelper(plan) {
+		if (this.helpers === void 0) {
+			const assets = this.opts.helperAssetsFor?.() ?? helperAssets();
+			this.helpers = assets === null ? null : new HelperRegistry(assets, (argv, options) => this.helperExec(argv, options), buildHelperProbeArgv, buildHelperUploadArgv);
+		}
+		if (this.helpers === null || this.disposed) return null;
+		try {
+			return await this.helpers.ensure(plan);
+		} catch {
+			return null;
+		}
+	}
+	async helperExec(argv, options) {
+		this.assertOpen();
+		const stdin = options?.stdin;
+		if (stdin !== void 0) {
+			const proc$1 = startBinaryProcess(argv, { timeoutSec: options?.timeoutSec });
+			proc$1.stdin.on("error", () => {});
+			proc$1.stdin.end(stdin);
+			return {
+				exit: (await proc$1.done).exit,
+				stdout: ""
+			};
+		}
+		const proc = startOneShot(argv, { timeoutSec: options?.timeoutSec });
+		return {
+			exit: (await proc.done).exit,
+			stdout: proc.read("stdout", 0).text
+		};
+	}
 	own(process$1) {
 		this.processes.add(process$1);
 		process$1.done.then(() => this.processes.delete(process$1));
 		return process$1;
 	}
-	/** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
-	/**
-	* Ruling P20 + PTY 候选表末位：裸名按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
-	* 撞名 ssh 优先），三段全不中再看池内活 PTY label，最后才是默认 ssh（交原生错误）。
-	* 位置即优先级：现有三段一位不挪。选择器前缀的 target 不经此路径。
-	*/
-	async resolveBareName(name$1, sessionKey, usePtyLabels = true) {
+	/** 现场采集机器面并 merge 进本 session 注册表（ssh → docker → incus → hub，迟到者加前缀）。错误逐段吞掉（roster 另行如实呈现）。 */
+	async refreshMachines(sessionKey) {
 		const runner = this.opts.rosterRunner ?? runOneShot;
 		const readCfg = this.opts.sshConfigReader ?? (async () => await readFile(join(homedir(), ".ssh", "config"), "utf8"));
-		let hosts = [];
+		let sshHosts = [];
 		try {
-			hosts = literalHosts(await readCfg()).hosts;
+			sshHosts = literalHosts(await readCfg()).hosts;
 		} catch {}
-		this.assertOpen();
-		if (hosts.some((h) => h.toLowerCase() === name$1.toLowerCase())) return {
-			kind: "ssh",
-			host: name$1
-		};
-		const docker = await runner([
+		const names = (argv) => (async () => {
+			const r = await runner(argv, { timeoutSec: 10 });
+			this.assertOpen();
+			return r.exit === 0 ? r.stdout.trim().split(/\r?\n/).map((l) => l.split(/[\t,]/)[0].trim()).filter((n) => n.length > 0) : [];
+		})().catch(() => []);
+		const [docker, incus] = await Promise.all([names([
 			"docker",
 			"ps",
 			"-a",
 			"--format",
 			"{{.Names}}"
-		], { timeoutSec: 10 });
-		this.assertOpen();
-		if (docker.exit === 0 && docker.stdout.trim().split(/\r?\n/).some((n) => n.trim().toLowerCase() === name$1.toLowerCase())) return {
-			kind: "docker",
-			container: name$1
-		};
-		const incus = await runner([
+		]), names([
 			"incus",
 			"list",
 			"--format",
 			"csv",
 			"--columns",
 			"n"
-		], { timeoutSec: 10 });
+		])]);
+		const hub = this.opts.getHub?.()?.listTargets().map((t) => t.id) ?? [];
+		this.labels.mergeScan(sessionKey, {
+			sshHosts,
+			docker,
+			incus,
+			hub
+		});
+	}
+	/** 池寻址：命中即回；miss 现场采集一次再寻址（docker 容器名不经 roster 也可达）。 */
+	async resolvePoolEntry(name$1, sessionKey) {
+		const hit = this.labels.resolve(name$1, sessionKey);
+		if (hit !== void 0) return hit;
+		await this.refreshMachines(sessionKey);
 		this.assertOpen();
-		if (incus.exit === 0 && incus.stdout.trim().split(/\r?\n/).some((n) => n.split(",")[0]?.trim().toLowerCase() === name$1.toLowerCase())) return {
-			kind: "incus",
-			container: name$1
+		const after = this.labels.resolve(name$1, sessionKey);
+		if (after !== void 0) return after;
+		return {
+			kind: "ssh",
+			name: name$1,
+			host: name$1
 		};
-		if (usePtyLabels && this.pool.get(`${sessionKey}|p:${name$1}`) !== void 0) return {
-			kind: "pty",
-			label: name$1
+	}
+	planOf(entry) {
+		switch (entry.kind) {
+			case "ssh": return {
+				kind: "ssh",
+				host: entry.host
+			};
+			case "ssh-byo": return {
+				kind: "ssh",
+				host: entry.connection.host,
+				connection: entry.connection
+			};
+			case "docker": return {
+				kind: "docker",
+				container: entry.container
+			};
+			case "incus": return {
+				kind: "incus",
+				container: entry.container
+			};
+			case "pty": throw new Error("remote: a PTY session is not a connection target");
+			case "hub": throw new Error("remote: hub machines are not connection targets");
+		}
+	}
+	/** ssh:<name> 的池感知解析：BYO 身份 → 其 connection；否则按 config 别名/主机名。 */
+	sshPlanFor(name$1, sessionKey) {
+		const entry = this.labels.resolve(name$1, sessionKey);
+		if (entry?.kind === "ssh-byo") return {
+			kind: "ssh",
+			host: entry.connection.host,
+			connection: entry.connection
 		};
 		return {
 			kind: "ssh",
 			host: name$1
 		};
 	}
-	/** Ruling P19：roster = 注意力入口——本地廉价扫描（ssh config/docker ps/incus list + 池内活会话），零拨号。
-	*  活的 pty 会话按调用方 agent session 过滤（2026-10-03 裁决）：ssh/docker/incus 是**公共静态配置**，
-	*  而活会话是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，且两个 agent 各开一条线
-	*  的代价可忽略。BYO-PTY 天然是活的，于是自然落进这个 scope，无需另立规则。 */
-	async roster(callCtx = {}) {
+	/** BYO ssh 注册（v2：无 spec 对比——label 占用即拒；注册成功才认领）。返回实际名（label 或 s-id）。 */
+	registerByoSsh(label, connection, sessionKey) {
 		this.assertOpen();
-		const prefix = `${callCtx.sessionKey ?? "no-session"}|`;
-		const sessions = this.pool.list().filter(({ key }) => key.startsWith(prefix)).map(({ key, snapshot }) => ({
-			target: displayKey(key),
-			state: snapshot.state,
-			idleSec: snapshot.idleMs !== null ? Math.round(snapshot.idleMs / 1e3) : null
-		}));
-		const runner = this.opts.rosterRunner ?? runOneShot;
-		const hub = this.opts.getHub?.();
-		return [...hub ? ["hub machines: " + (hub.listTargets().map((t) => `hub:${t.id} (${t.label}${t.execEnabled ? "" : "; exec disabled"})`).join(", ") || "none")] : [], await renderRoster(sessions, {
-			byosshLabels: this.sshTargets.entries().map(([label]) => label),
-			readSshConfig: this.opts.sshConfigReader,
-			runner: (argv, options) => {
-				this.assertOpen();
-				return runner(argv, options);
-			}
-		})].join("\n");
+		const normalized = normalizeSshConnection(connection);
+		if (label !== void 0) validateLabel(label);
+		const name$1 = label ?? this.labels.freshId("ssh-", sessionKey);
+		if (label !== void 0) {
+			const existing = this.labels.resolve(label, sessionKey);
+			if (existing !== void 0) throw new Error(`[E_LABEL_IN_USE] remote: label ${JSON.stringify(label)} is already taken by ${describeEntry(existing)} — nothing was run.\n  To reuse it:    address ssh:${label} without the ssh field\n  To register new: pick another label`);
+			this.labels.claim(label, sessionKey, {
+				kind: "ssh-byo",
+				name: label,
+				connection: normalized
+			});
+			return label;
+		}
+		this.labels.claim(name$1, sessionKey, {
+			kind: "ssh-byo",
+			name: name$1,
+			connection: normalized
+		});
+		return name$1;
 	}
-	async status(target, callCtx = {}) {
+	/** PTY 会话创建（native/spawn 同一形状）：上限 → label 认领 → 惰性会话（失败由 onDead 释放 label）。 */
+	createSession(opts, sessionKey) {
 		this.assertOpen();
-		if (target.startsWith("hub:")) {
-			const machine = target.slice(4);
-			const row = this.requireHub().listTargets().find((t) => t.id === machine);
-			if (!row) throw new Error(`unknown remote machine ${machine} — select a remote machine from the Hub roster; local execution is not available`);
-			return `${target} — Hub remote machine (${row.label}); exec ${row.execEnabled ? "enabled" : "disabled"}; not probed`;
+		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}`);
 		}
-		const sessionKey = callCtx.sessionKey ?? "no-session";
-		const label = target.startsWith("byop:") ? target.slice(5) : void 0;
-		if (label !== void 0) return this.ptyStatus(target, label, sessionKey);
-		const direct = /^(docker|incus|ssh):/.test(target);
-		const resolved = target.startsWith("byossh:") ? this.byosshPlan(target) : direct ? resolveTarget(target) : await this.resolveBareName(target, sessionKey);
-		this.assertOpen();
-		if (resolved.kind === "pty") return this.ptyStatus(`byop:${resolved.label}`, resolved.label, sessionKey);
-		const head = `${target} — ${resolved.kind === "ssh" ? "ssh host" : `${resolved.kind} container`}`;
-		const runner = this.opts.probeRunner ?? runOneShot;
-		return [
-			head,
-			renderProbe(await probeTarget(resolved, { runner: (argv, options) => {
-				this.assertOpen();
-				return runner(argv, options);
-			} })),
-			renderSession(this.pool.inspect(`${sessionKey}|t:${target}`))
-		].join("\n");
+		const { label } = opts;
+		if (label !== void 0) validateLabel(label);
+		const id = this.labels.freshId("pty-", sessionKey);
+		const entry = {
+			kind: "pty",
+			name: id,
+			id,
+			...label !== void 0 ? { label } : {},
+			connection: opts.connection,
+			byo: opts.byo
+		};
+		if (label !== void 0) this.labels.claim(label, sessionKey, {
+			...entry,
+			name: label
+		});
+		const key = `${sessionKey}|p:${id}`;
+		let session;
+		try {
+			session = this.pool.create({
+				key,
+				argv: opts.argv,
+				id,
+				...label !== void 0 ? { label } : {},
+				connection: opts.connection,
+				byo: opts.byo,
+				builtOn: this.isBuiltOn(opts.connection, sessionKey),
+				...opts.origin !== void 0 ? { origin: opts.origin } : {},
+				onDead: () => {
+					this.labels.release(id, sessionKey);
+					if (label !== void 0) this.labels.release(label, sessionKey);
+				}
+			});
+		} catch (error) {
+			this.labels.release(id, sessionKey);
+			if (label !== void 0) this.labels.release(label, sessionKey);
+			throw error;
+		}
+		this.labels.claim(id, sessionKey, entry);
+		return session;
 	}
-	/** PTY 状态行：纯池内读取，零拨号（label 从来不是可拨目标）。 */
-	ptyStatus(display, label, sessionKey) {
-		return [`${display} — BYO pty session`, renderPtySession(this.pool.inspect(`${sessionKey}|p:${label}`))].join("\n");
+	ttlMinutes() {
+		return Math.max(1, Math.round(this.ptyIdleTtlSec / 60));
 	}
-	/** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径（成功被毒化成失败+双重审计）。 */
-	audit(r) {
-		try {
-			this.opts.onAudit?.(r);
-		} catch {}
+	/** connection 由 BYO ssh 身份建立 → card 面标 `(built on)`（与 roster 同词，R2 复核 P2-10）。 */
+	isBuiltOn(connection, sessionKey) {
+		return connection.startsWith("ssh:") && this.labels.resolve(connection.slice(4), sessionKey)?.kind === "ssh-byo";
 	}
-	/** Registration never dials; response reveals labels only, not credentials. */
-	registerSsh(target, connection) {
-		this.assertOpen();
-		if (!target.startsWith("byossh:")) throw new Error("[E_SSH_PARAMS] remote: ssh requires a byossh:<label> target");
-		this.sshTargets.register(target.slice(7), connection);
-		return `${target} registered (no dialing). Reuse this Agent's label without ssh; a new Agent/cold resume must register again.`;
-	}
-	byosshPlan(target, connection) {
-		if (connection !== void 0) this.registerSsh(target, connection);
-		const spec = this.sshTargets.get(target.slice(7));
-		if (!spec) throw new Error(`[E_NO_SSH_TARGET] remote: ${target} is not registered in this Agent — supply ssh:{host,user?,port?,key?,proxyJump?} first; key must be an existing origin file path`);
-		return {
-			kind: "ssh",
-			host: spec.host,
-			connection: spec
-		};
+	/** PTY 创建形唯一实现（execute 与 background 预建共用）：spawn BYO / ssh BYO / native `<transport>:pty`。 */
+	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;
+			if (label !== void 0 && PTY_ID_RE.test(label)) throw new Error(`[E_BAD_LABEL] remote: ${JSON.stringify(label)} looks like an auto id — ids are generated, labels are yours to choose`);
+			return { session: this.createSession({
+				argv: (this.opts.spawnArgvFor ?? buildSpawnArgv)(params.spawn),
+				connection: "BYOP",
+				byo: true,
+				...label !== void 0 ? { label } : {},
+				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
+			};
+			return { session: this.createSession({
+				argv: (this.opts.ptyArgvFor ?? buildPtyArgv)(plan),
+				connection: `ssh:${name$1}`,
+				byo: false,
+				...form.label !== void 0 ? { label: form.label } : {}
+			}, sessionKey) };
+		}
+		if (form.form === "create-pty") {
+			const plan = form.transport === "ssh" ? this.sshPlanFor(form.name, sessionKey) : resolveTarget(`${form.transport}:${form.name}`);
+			return { session: this.createSession({
+				argv: (this.opts.ptyArgvFor ?? buildPtyArgv)(plan),
+				connection: `${form.transport}:${form.name}`,
+				byo: false,
+				...form.label !== void 0 ? { label: form.label } : {}
+			}, sessionKey) };
+		}
+		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}`,
+				byo: false,
+				...form.label !== void 0 ? { label: form.label } : {}
+			}, sessionKey) };
+		}
 	}
-	/** Single target resolver for later copy/rsync; BYO identities cannot be
-	* independently re-resolved through the origin's alias table. */
-	async resolveConnectionTarget(target, callCtx = {}) {
+	/** background PTY lane：会话先占位（不拨号）再进官方 jobs registry——首回执必须能寻址；
+	* registry 拒绝时把新建的会话拆掉（复用形的会话绝不拆）。返回 undefined = 走普通 oneshot job。 */
+	async preparePtyLane(params, callCtx = {}) {
 		this.assertOpen();
-		if (target.startsWith("byossh:")) return this.byosshPlan(target);
-		if (/^(docker|incus|ssh):/.test(target)) return resolveTarget(target);
-		if (/^(byop|hub):/.test(target)) throw new Error("remote: select an SSH/Docker/Incus target for this connection resolver");
-		const plan = await this.resolveBareName(target, callCtx.sessionKey ?? "no-session", false);
+		const prepared = await prepareRemoteInput(params);
 		this.assertOpen();
-		if (plan.kind === "pty") throw new Error("remote: BYO-PTY is not a filesystem connection");
-		return plan;
-	}
-	route(params) {
-		const hasTarget = params.target !== void 0 && params.target.length > 0;
-		const hasSpawn = params.spawn !== void 0 && params.spawn.length > 0;
-		if (!hasTarget && !hasSpawn) throw new Error("[E_PARAMS] remote: target is required (e.g. { target: \"dev4\", cmd: \"git status\" }); spawn is a modifier of a \"byop:<label>\" target and cannot stand alone");
-		if (params.timeout !== void 0 && (!Number.isFinite(params.timeout) || params.timeout <= 0)) throw new Error(`[E_BAD_TIMEOUT] remote: timeout must be a positive number of seconds (got ${JSON.stringify(params.timeout)})`);
-		if (params.stdin !== void 0 && (params.cmd === void 0 || params.cmd.length === 0)) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd");
-		if (params.ssh !== void 0 && !params.target.startsWith("byossh:")) throw new Error("[E_SSH_PARAMS] remote: ssh requires a byossh:<label> target");
-		if (params.target.startsWith("byossh:")) {
-			if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn is only for byop:<label>, not BYO-SSH");
+		const sessionKey = callCtx.sessionKey ?? "no-session";
+		const form = parseTargetForm(prepared.target);
+		const target = (id$1) => ({
+			target: `pty:${id$1}`,
+			cmd: params.cmd,
+			stdin: params.stdin,
+			timeout: params.timeout,
+			mode: "pty"
+		});
+		const lane = this.createPtyLane(prepared, form, sessionKey);
+		if (lane === void 0 && 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) or pass spawn to create one");
+			const id$1 = this.resolvePty(form.idOrLabel, sessionKey).identity;
 			return {
-				mode: params.mode ?? "oneshot",
-				display: params.target,
-				plan: this.byosshPlan(params.target, params.ssh)
+				input: target(id$1.id),
+				session: `pty:${id$1.id}`,
+				connection: id$1.connection,
+				...id$1.label !== void 0 ? { label: id$1.label } : {},
+				cleanup: () => void 0
 			};
 		}
-		if (hasTarget && params.target.startsWith("byop:")) {
-			const label = params.target.slice(5);
-			if (!PTY_LABEL_RE.test(label)) throw new Error(`[E_BAD_LABEL] remote: PTY label must match ${PTY_LABEL_RE.source} (got ${JSON.stringify(label)}) — e.g. target: "byop:dev3"`);
-			if (params.mode !== void 0 && params.mode !== "pty") throw new Error(`[E_BAD_MODE] remote: "${params.target}" is a PTY selector — mode is locked to 'pty'`);
-			return {
-				mode: "pty",
-				display: params.target,
-				pty: {
-					label,
-					...hasSpawn ? { spawn: params.spawn } : {}
-				}
-			};
+		if (lane === void 0) return void 0;
+		const id = lane.session.identity;
+		return {
+			input: target(id.id),
+			session: `pty:${id.id}`,
+			connection: id.connection,
+			...id.label !== void 0 ? { label: id.label } : {},
+			cleanup: () => {
+				lane.session.dispose();
+			}
+		};
+	}
+	/** `pty:<id|label>` 寻址：先 id 后 label；miss 给重建形式。 */
+	resolvePty(selector, sessionKey) {
+		const entry = this.labels.resolve(selector, sessionKey);
+		if (entry?.kind === "pty") {
+			const s = this.pool.get(`${sessionKey}|p:${entry.id}`);
+			if (s !== void 0) return s;
 		}
-		if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn requires a \"byop:<label>\" target — e.g. { target: \"byop:dev3\", spawn: \"ssh dev3\", cmd: \"…\" }; it is not a standalone entry point");
-		const mode = params.mode ?? "oneshot";
-		if (params.target.startsWith("hub:")) return {
-			mode,
-			display: params.target
+		throw new Error(`[E_NO_SESSION] remote: no live PTY under ${PTY_ID_RE.test(selector) ? `id ${selector}` : `label ${JSON.stringify(selector)}`} — sessions are created by appending :pty to a transport target ({target:"ssh:dev4:pty", cmd:"…"}) or by spawn; idle sessions are reaped after ${this.ttlMinutes()} min`);
+	}
+	/** §6 close：默认撞 detached job 报错（列杀法）；force = 杀组+关闭（披露 killed）。幂等 not-found。 */
+	closePty(selector, sessionKey, force = false) {
+		this.assertOpen();
+		const entry = this.labels.resolve(selector, sessionKey);
+		if (entry?.kind !== "pty") return {
+			session: selector,
+			connection: "",
+			closed: false,
+			reason: "not-found",
+			killed: [],
+			message: `no pty session is registered under ${JSON.stringify(selector)}`
+		};
+		const session = this.pool.get(`${sessionKey}|p:${entry.id}`);
+		if (session === void 0) return {
+			session: `pty:${entry.id}`,
+			connection: entry.connection,
+			closed: false,
+			reason: "already-closed-or-reaped",
+			killed: [],
+			message: `pty:${entry.id} was already closed or reaped after ${this.ttlMinutes()} min idle`
 		};
-		const direct = /^(docker|incus|ssh):/.test(params.target);
+		const pending = session.detachedCommandId;
+		if (pending !== null && !force) throw new Error(`[E_SESSION_BUSY] remote: pty session ${entry.id} still runs a detached command (${pending}) — job_kill ${pending} first (or wait for it), then close again; force:true closes the tab and kills the group in one step`);
+		session.dispose();
 		return {
-			mode,
-			display: params.target,
-			...direct ? { plan: resolveTarget(params.target) } : { bare: params.target }
+			session: `pty:${entry.id}`,
+			connection: entry.connection,
+			closed: true,
+			...pending !== null ? { killed: [pending] } : { killed: [] }
 		};
 	}
-	async execute(params, routing, callCtx) {
-		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
-		const cap = this.opts.maxOutputChars ?? 3e4;
-		if (routing.display.startsWith("hub:")) {
+	/** job 通道收养回填（timeout handoff 时 registry id ≠ commandId，账本记录两者）。 */
+	attachPtyJob(commandId, jobId, sessionKey) {
+		for (const { key } of this.pool.list()) {
+			if (!key.startsWith(`${sessionKey ?? "no-session"}|`)) continue;
+			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 供工具层渲染。 */
+	async input(target, options, callCtx = {}) {
+		this.assertOpen();
+		const sessionKey = callCtx.sessionKey ?? "no-session";
+		const form = parseTargetForm(target);
+		let selector;
+		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);
+		const receipt = await session.input(options);
+		const id = session.identity;
+		return {
+			...receipt,
+			connection: id.connection,
+			...id.label !== void 0 ? { label: id.label } : {}
+		};
+	}
+	async dispatchPty(session, params, callCtx, timeoutSec, cap) {
+		const hubConn = session.identity.connection;
+		if (hubConn.startsWith("hub:")) {
 			const hub = this.requireHub();
 			this.hubProviders.add(hub);
-			const machine = routing.display.slice(4);
-			if (routing.mode === "pty") {
-				const result$1 = await hub.pty(machine, params.cmd, this.hubOwner, {
-					stdin: params.stdin,
-					timeout: timeoutSec
-				});
-				const out$2 = tailWindow(result$1.stdout, cap, result$1.outputStats?.stdout);
-				return {
-					...result$1,
-					stdout: out$2.text,
-					...out$2.stats ? { outputStats: {
-						...result$1.outputStats,
-						stdout: out$2.stats
-					} } : {},
-					...out$2.truncated === void 0 ? {} : { truncated: out$2.truncated }
-				};
-			}
-			const process$1 = this.own(await hub.start(machine, {
-				...params,
-				target: routing.display,
-				mode: "oneshot",
-				timeout: timeoutSec
-			}, this.hubOwner));
-			if (this.disposed) process$1.cancel("owner disposed");
-			const result = await process$1.done;
-			const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
-			const out$1 = tailWindow(stdout.text, cap, stdout.stats);
-			const err = tailWindow(stderr.text, cap, stderr.stats);
-			return {
-				...result,
-				mode: "oneshot",
-				target: routing.display,
-				cwd: null,
-				reconnected: false,
-				stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out$1.text,
-				stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
-				...out$1.stats ? { outputStats: {
-					stdout: out$1.stats,
-					stderr: err.stats
-				} } : { outputStatsUnavailable: true },
-				...out$1.truncated === void 0 ? {} : { truncated: out$1.truncated }
-			};
-		}
-		const sessionKey = callCtx.sessionKey ?? "no-session";
-		if (routing.bare !== void 0) {
-			const resolved = await this.resolveBareName(routing.bare, sessionKey, params.mode !== "oneshot");
-			this.assertOpen();
-			if (resolved.kind === "pty") {
-				routing.pty = { label: resolved.label };
-				routing.mode = "pty";
-				routing.display = `byop:${resolved.label}`;
-			} else routing.plan = resolved;
-		}
-		if (routing.pty !== void 0) return await this.ptyCall(routing.pty, params, sessionKey, timeoutSec, cap);
-		if (routing.mode === "oneshot") {
-			this.assertOpen();
-			const process$1 = this.own(await this.nativeProcess(routing.plan, 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);
-			const r$1 = {
-				...result,
-				stdout: stdout.text,
-				stderr: [stderr.text, stderr.diagnostic].filter(Boolean).join("\n"),
-				outputStats: {
-					stdout: stdout.stats,
-					stderr: stderr.stats
-				}
-			};
-			const out$1 = tailWindow(r$1.stdout, cap, r$1.outputStats?.stdout);
-			const err = r$1.stderr.length > 0 ? tailWindow(r$1.stderr, cap, r$1.outputStats?.stderr) : void 0;
-			return {
-				mode: "oneshot",
-				target: routing.display,
-				exit: r$1.exit,
-				cwd: null,
-				timedOut: r$1.timedOut,
-				reconnected: false,
-				stdout: out$1.text,
-				...err !== void 0 ? { stderr: err.text } : {},
-				...out$1.stats ? { outputStats: {
-					stdout: out$1.stats,
-					stderr: err?.stats ?? r$1.outputStats?.stderr
-				} } : {},
-				durationMs: r$1.durationMs,
-				...out$1.truncated !== void 0 ? { truncated: out$1.truncated } : {}
-			};
+			hub.ptyEndpoint(hubConn.slice(4));
 		}
-		const argv = (this.opts.ptyArgvFor ?? buildPtyArgv)(routing.plan);
-		const key = `${sessionKey}|t:${routing.display}`;
-		const r = await this.pool.getOrCreate(key, argv).dispatch(params.cmd, {
+		const commandId = callCtx.commandId ?? genCommandId();
+		const r = await session.dispatch(params.cmd, {
 			stdin: params.stdin,
-			timeoutSec
+			timeoutSec,
+			commandId,
+			...callCtx.ptyBackground === true ? {
+				background: true,
+				jobId: commandId
+			} : {}
 		});
 		const out = tailWindow(r.output, cap, r.outputStats?.stdout);
+		const id = session.identity;
 		return {
 			mode: "pty",
-			target: routing.display,
+			target: `pty:${id.id}`,
+			session: `pty:${id.id}`,
+			...id.label !== void 0 ? { label: id.label } : {},
+			connection: id.connection,
+			...id.byo ? { byoTag: "byo-pty" } : {},
+			commandId: r.commandId,
 			exit: r.exit,
 			cwd: r.cwd,
 			timedOut: r.timedOut,
@@ -2803,42 +3944,211 @@ var RemoteDriver = class {
 			stdout: out.text,
 			outputStats: out.stats ? { stdout: out.stats } : void 0,
 			durationMs: r.durationMs,
-			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
+			...out.truncated !== void 0 ? { truncated: out.truncated } : {},
+			...r.envDelta !== void 0 ? { envDelta: r.envDelta } : {},
+			...r.running === true && r.job !== void 0 ? {
+				running: true,
+				ptyJob: r.job
+			} : {},
+			...this.ptyTtl(session.key)
 		};
 	}
-	/** BYO-PTY 通道：label 即池键（agent 前缀之外），spawn 只在 label 尚不存在时被接受。
-	* 三分支 —— 建（无会话）/ 复用（无 spawn，或有 spawn 且与创建来源相同）/ **冲突（有 spawn 且来源不同：不执行任何命令）**。 */
-	async ptyCall(pty, params, sessionKey, timeoutSec, cap) {
-		const display = `byop:${pty.label}`;
-		const key = `${sessionKey}|p:${pty.label}`;
-		const existing = this.pool.get(key);
-		let session = existing;
-		let notice;
-		if (existing !== void 0 && pty.spawn !== void 0 && existing.origin !== pty.spawn) throw new Error(`[E_LABEL_CONFLICT] remote: ${display} already exists and was created by a different command — nothing was run.\n  existing spawn: ${JSON.stringify(existing.origin)}\n  given spawn:    ${JSON.stringify(pty.spawn)}\n  To reuse it:    { target: "${display}", cmd: "…" }   (drop spawn — spawn only ever creates)\n  To start new:   pick another label, e.g. { target: "byop:${pty.label}2", spawn: ${JSON.stringify(pty.spawn)}, cmd: "…" }`);
-		if (session === void 0) {
-			if (pty.spawn === void 0) throw new Error(`[E_NO_SESSION] remote: no live PTY under ${display} — one exists only after a call that supplies spawn, and it is reaped after the idle TTL (600s).\n  Create it:      { target: "${display}", spawn: "…", cmd: "…" }   (the spawn command is not retained; the label is yours to choose)`);
-			session = this.pool.getOrCreate(key, (this.opts.spawnArgvFor ?? buildSpawnArgv)(pty.spawn), pty.spawn);
-		} else if (pty.spawn !== void 0) notice = `[remote: ${display} already runs that exact command and is persistent — reuse it with { target: "${display}", cmd: "…" }; spawn is only needed to create.]`;
-		const r = await session.dispatch(params.cmd, {
-			stdin: params.stdin,
-			timeoutSec
-		});
-		const out = tailWindow(r.output, cap, r.outputStats?.stdout);
+	/** 预热（创建形无 cmd）回执：§3——无 commandId/envDelta；timeout 忽略。 */
+	warmReceipt(session) {
+		const id = session.identity;
+		return {
+			mode: "pty",
+			target: `pty:${id.id}`,
+			session: `pty:${id.id}`,
+			...id.label !== void 0 ? { label: id.label } : {},
+			connection: id.connection,
+			...id.byo ? { byoTag: "byo-pty" } : {},
+			created: true,
+			exit: null,
+			cwd: null,
+			timedOut: false,
+			reconnected: false,
+			stdout: "",
+			durationMs: 0,
+			...this.ptyTtl(session.key)
+		};
+	}
+	/** session card 回执（`pty:<id|label>` 无 cmd）：connection/state/cwd + 最近 20 条账本（不带输出尾，§9 Q7）。 */
+	cardReceipt(session) {
+		const id = session.identity;
+		const snap = session.snapshot;
+		const state = snap.busy ? "busy (a command is running)" : snap.state === "dead" ? "died — next dispatch reconnects a fresh shell" : `idle ${Math.round((snap.idleMs ?? 0) / 1e3)}s (connected)`;
+		const head = `pty:${id.id}${id.label !== void 0 ? ` (label ${id.label})` : ""} — ${id.connection}${id.byo ? " (byo-pty)" : id.builtOn ? " (built on)" : ""} · ${state} · cwd ${session.lastCwd ?? "(none yet)"}`;
 		return {
 			mode: "pty",
+			target: `pty:${id.id}`,
+			session: `pty:${id.id}`,
+			...id.label !== void 0 ? { label: id.label } : {},
+			connection: id.connection,
+			...id.byo ? { byoTag: "byo-pty" } : {},
+			exit: null,
+			cwd: session.lastCwd,
+			timedOut: false,
+			reconnected: false,
+			stdout: [head, renderLedger(session.ledgerSnapshot())].join("\n"),
+			durationMs: 0,
+			...this.ptyTtl(session.key)
+		};
+	}
+	async oneshot(plan, display, params, timeoutSec, cap) {
+		this.assertOpen();
+		const process$1 = this.own(await this.nativeProcess(plan, 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);
+		const r = {
+			...result,
+			stdout: stdout.text,
+			stderr: [stderr.text, stderr.diagnostic].filter(Boolean).join("\n"),
+			outputStats: {
+				stdout: stdout.stats,
+				stderr: stderr.stats
+			}
+		};
+		const out = tailWindow(r.stdout, cap, r.outputStats?.stdout);
+		const err = r.stderr.length > 0 ? tailWindow(r.stderr, cap, r.outputStats?.stderr) : void 0;
+		return {
+			mode: "oneshot",
 			target: display,
-			session: display,
 			exit: r.exit,
-			cwd: r.cwd,
+			cwd: null,
 			timedOut: r.timedOut,
-			reconnected: r.reconnected,
+			reconnected: false,
 			stdout: out.text,
-			...notice !== void 0 ? { notice } : {},
-			outputStats: out.stats ? { stdout: out.stats } : void 0,
+			...err !== void 0 ? { stderr: err.text } : {},
+			...out.stats ? { outputStats: {
+				stdout: out.stats,
+				stderr: err?.stats ?? r.outputStats?.stderr
+			} } : {},
 			durationMs: r.durationMs,
-			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
+			...out.truncated !== void 0 ? { truncated: out.truncated } : {},
+			...this.runnerOf.get(process$1) === void 0 ? {} : { runner: this.runnerOf.get(process$1) }
+		};
+	}
+	async hubOneshot(machine, display, params, timeoutSec, cap) {
+		const process$1 = this.own(await this.hubOneshotProcess(machine, params));
+		if (this.disposed) process$1.cancel("owner disposed");
+		const result = await process$1.done;
+		const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
+		const out = tailWindow(stdout.text, cap, stdout.stats);
+		const err = tailWindow(stderr.text, cap, stderr.stats);
+		return {
+			...result,
+			mode: "oneshot",
+			target: display,
+			connection: display,
+			cwd: null,
+			reconnected: false,
+			runner: HUB_RUNNER,
+			stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out.text,
+			stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
+			...out.stats ? { outputStats: {
+				stdout: out.stats,
+				stderr: err.stats
+			} } : { outputStatsUnavailable: true },
+			...out.truncated === void 0 ? {} : { truncated: out.truncated }
 		};
 	}
+	async hubOneshotProcess(machine, params) {
+		const hub = this.requireHub();
+		this.hubProviders.add(hub);
+		return await hub.start(machine, {
+			...params,
+			target: `hub:${machine}`,
+			mode: "oneshot"
+		}, this.hubOwner);
+	}
+	/** Ruling P19 + §2.5：roster = 注意力入口——本地扫描刷新统一池，零拨号；机器面公共，会话面 caller-scoped。 */
+	async roster(callCtx = {}) {
+		this.assertOpen();
+		const scan = await scanLocal({
+			runner: this.opts.rosterRunner,
+			readSshConfig: this.opts.sshConfigReader
+		});
+		this.assertOpen();
+		this.labels.mergeScan(callCtx.sessionKey ?? "no-session", {
+			sshHosts: scan.ssh.hosts,
+			docker: scan.docker.rows.map((r) => r.name),
+			incus: scan.incus.rows.map((r) => r.name),
+			hub: this.opts.getHub?.()?.listTargets().map((t) => t.id) ?? []
+		});
+		const prefix = `${callCtx.sessionKey ?? "no-session"}|`;
+		const sessions = this.pool.list().filter(({ key }) => key.startsWith(prefix)).map(({ key }) => {
+			const s = this.pool.get(key);
+			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());
+	}
+	/** 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") {
+			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`;
+		}
+		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.cardReceipt(this.resolvePty(form.idOrLabel, sessionKey)).stdout;
+		}
+		if (form.form !== "direct" && form.form !== "bare") throw new Error("[E_PARAMS] remote: status takes a machine target (bare name or ssh:/docker:/incus:/hub:) or a pty:<id|label> selector");
+		const name$1 = directName(form) || (form.form === "bare" ? form.name : "");
+		const entry = await this.resolvePoolEntry(name$1, sessionKey);
+		this.assertOpen();
+		if (entry.kind === "pty") {
+			if (form.form !== "bare") throw new Error("[E_TARGET_FORMAT] remote: ssh:/docker:/incus: force a machine channel — the pty selector is pty:<id|label>");
+			return this.cardReceipt(this.resolvePty(form.name, sessionKey)).stdout;
+		}
+		if (entry.kind === "hub") return this.status(`hub:${entry.machine}`, callCtx);
+		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 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}`);
+		return [
+			head,
+			renderProbe(probe),
+			onConnection.length > 0 ? `pty sessions on this connection: ${onConnection.map(sessionLine).join(" · ")}` : "pty sessions on this connection: none"
+		].join("\n");
+	}
+	/** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径。 */
+	audit(r) {
+		try {
+			this.opts.onAudit?.(r);
+		} catch {}
+	}
+	/** Single target resolver for later copy/rsync; PTY sessions are not filesystem connections. */
+	async resolveConnectionTarget(target, callCtx = {}) {
+		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 === "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");
+		this.assertOpen();
+		return this.planOf(entry);
+	}
+	/** P2/P3：回执即状态快照——idle TTL 剩余随每次 pty 回执带回。 */
+	ptyTtl(key) {
+		const snap = this.pool.inspect(key);
+		if (snap === void 0 || snap.state === "dead" || snap.state === "disposed") return {};
+		if (snap.idleMs === null) return { ttlSec: this.ptyIdleTtlSec };
+		return { ttlSec: Math.max(0, Math.round(this.ptyIdleTtlSec - snap.idleMs / 1e3)) };
+	}
 	hasHub() {
 		return this.opts.getHub?.() !== void 0;
 	}
@@ -2853,8 +4163,8 @@ var RemoteDriver = class {
 	}
 	dispose() {
 		if (this.disposal) return this.disposal;
-		this.sshTargets.clear();
 		this.disposed = true;
+		this.labels.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 () => {
@@ -2868,13 +4178,87 @@ var RemoteDriver = class {
 		})();
 	}
 };
+/** direct 形态回退到 resolveTarget 可解析的名字（ssh:dev4 → dev4）。 */
+function directName(form) {
+	return form.form === "direct" ? form.name : form.form === "create-pty" ? form.name : "";
+}
+/** roster/status 一行的会话描述：`p-ab12 (label build) ssh:dev4 idle 12s`。 */
+function sessionLine(s) {
+	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 `${id.id}${id.label !== void 0 ? ` (label ${id.label})` : ""} ${id.connection}${id.byo ? " (byo-pty)" : ""} ${state}`;
+}
 
 //#endregion
 //#region src/remote/jobs.ts
+/** PTY job 的单通道输出：流在 PTY 里天然合并，无独立 stderr 通道（P5 如实披露）。
+* read 是 byte-cursor 增量（Utf16TailRing.read 语义：逐字节游标 + lossy 报尾环逐出）。 */
+const ptyOutputSources = (holder) => [{
+	channel: "stdout",
+	read: (fromByte) => holder.job?.read(fromByte) ?? {
+		text: "",
+		nextOffset: fromByte,
+		lossy: false
+	}
+}];
+/** 0.3.2-d CF：timedOut=true 且 aborted=false = 会话侧主动收束（close force / 行回收走的
+* dispose→interrupt 两段路）——同为 killed；exit 到手用 exit，只剩会话死亡时写 session closed。 */
+const ptyOutcome = (aborted, result) => {
+	const interrupted = aborted || result.timedOut === true;
+	return {
+		status: interrupted ? "killed" : result.exit === null ? "failed" : "completed",
+		detail: interrupted ? `interrupted: ${result.exit === null ? aborted ? "session died" : "session closed" : `exit ${result.exit}`}` : result.exit === null ? "session died" : `exit code: ${result.exit}`
+	};
+};
 /** No preparation or discovery before the official registry's admission. */
 function startRemoteJob(registry, input, exec, driver) {
-	if (input.mode === "pty" || input.spawn !== void 0 || input.target?.startsWith("byop:")) throw new Error("remote: background execution requires oneshot; PTY and BYO-PTY are unsupported");
 	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 holder = {};
+		return registry.start({
+			kind: "remote",
+			owner: exec.agent.id,
+			label: `${input.target}: ${input.cmd}`,
+			output: ptyOutputSources(holder),
+			run(job) {
+				const controller = new AbortController();
+				return {
+					done: (async () => {
+						try {
+							const r = await driver.call({
+								...input,
+								mode: "pty"
+							}, {
+								ptyBackground: true,
+								commandId: job.id,
+								sessionKey: exec.agent?.id ?? "no-session"
+							});
+							if (r.running !== true || r.ptyJob === void 0) return {
+								status: "failed",
+								detail: "pty dispatch did not hand off a running job"
+							};
+							holder.job = r.ptyJob;
+							if (controller.signal.aborted) r.ptyJob.interrupt();
+							const outcome = await r.ptyJob.done;
+							return ptyOutcome(controller.signal.aborted, outcome);
+						} catch (error) {
+							return {
+								status: controller.signal.aborted ? "killed" : "failed",
+								detail: error instanceof Error ? error.message : String(error)
+							};
+						}
+					})(),
+					cancel(reason) {
+						if (controller.signal.aborted) return;
+						controller.abort(reason);
+						holder.job?.interrupt();
+					}
+				};
+			}
+		});
+	}
 	let process$1;
 	const output = ["stdout", "stderr"].map((channel) => ({
 		channel,
@@ -2894,7 +4278,7 @@ function startRemoteJob(registry, input, exec, driver) {
 	return registry.start({
 		kind: "remote",
 		owner: exec.agent.id,
-		label: `${input.target}: ${input.cmd ?? input.script}`,
+		label: `${input.target}: ${input.cmd}`,
 		output,
 		run() {
 			const controller = new AbortController();
@@ -2904,7 +4288,7 @@ function startRemoteJob(registry, input, exec, driver) {
 						process$1 = await driver.start({
 							...input,
 							mode: "oneshot"
-						}, controller.signal);
+						}, controller.signal, { sessionKey: exec.agent?.id ?? "no-session" });
 						if (controller.signal.aborted) process$1.cancel(controller.signal.reason);
 						const result = await process$1.done;
 						const diagnostic = process$1.read("stderr", 0).diagnostic;
@@ -2928,82 +4312,351 @@ function startRemoteJob(registry, input, exec, driver) {
 		}
 	});
 }
+/** P4（2026-10-19）handoff 收养：同步 pty dispatch 超时后命令仍在跑——注册成 job，
+* job_output 即增量轮询、job_kill 即显式中断（P8 ^C+130-marker，会话存活）。 */
+function adoptRunningPtyJob(registry, exec, label, job) {
+	if (!exec.agent) throw new Error("remote: background jobs require a live Agent owner");
+	return registry.start({
+		kind: "remote",
+		owner: exec.agent.id,
+		label,
+		output: ptyOutputSources({ job }),
+		run() {
+			const controller = new AbortController();
+			return {
+				done: (async () => {
+					if (controller.signal.aborted) job.interrupt();
+					const outcome = await job.done;
+					return ptyOutcome(controller.signal.aborted, outcome);
+				})(),
+				cancel(reason) {
+					if (controller.signal.aborted) return;
+					controller.abort(reason);
+					job.interrupt();
+				}
+			};
+		}
+	});
+}
 
 //#endregion
 //#region src/remote/tool.ts
-const NO_SESSION_KEY = "remote:no-session";
+const NO_SESSION_KEY$1 = "remote:no-session";
 /**
-* The model-visible surface of the `remote` tool. Kept as ONE template
-* literal so it can be edited here directly — no string concatenation and no
-* apostrophe escaping. Plain text only: no backticks and no "${" inside.
+* The model-visible surface of the `remote` tool (0.3.2-d user-ruled restructure:
+* Actions / Targets / PTY / Oneshot / Examples — the PTY block is the user's verbatim
+* final draft; Examples receipts match renderValue byte-for-byte).
+* ONE template literal — no backticks, no "${".
+*
+* 语义目标（surface 就是产品）：动作是唯一的派发维度；PTY 四词定位——stateful oneshot /
+* interact-able stdin / managed output / persistent env——回执形状与 oneshot 相同、只增状态，
+* 运行中的命令可分步观察后再补输（input 动作）；多步与交互任务默认进 PTY。
 */
-const REMOTE_TOOL_DESCRIPTION = `Remote execution and file transfer over ssh / docker / incus, plus persistent named shells. Pick the call shape:
-  {}                       → roster (local scan, no dialing)
-  {target}                 → status probe: reachable / unreachable — <native error>, or container state + session layer
-  {target, cmd}            → run cmd — oneshot by default; mode "pty" for a persistent shell
-  {target, script:"/abs"}  → LOCAL script over stdin to a fixed bash -s (oneshot only; no cmd/stdin/spawn/mode mix)
-  {target:"byossh:lbl", ssh:{host,user?,port?,key?,proxyJump?}} → register this Agent's SSH identity (no cmd = register only); reuse the target later with ssh omitted. Same spec idempotent; different spec refused — use another label. key is an existing origin file, never inline material; nothing written or persisted; a new Agent registers again.
-  {target:"byop:lbl", spawn, cmd} → create the named shell once; reuse as {target:"byop:lbl", cmd} (no spawn)
-Bare names resolve ssh config → docker → incus → live pty; unmatched goes to ssh and its native error surfaces. Prefixes ssh: / docker: / incus: / byop: force a channel. byop: same spawn repeated is reused; a different spawn is refused ([E_LABEL_CONFLICT], nothing runs); unknown or idle-expired → [E_NO_SESSION] (spawn is not retained — pass it again); a failed spawn frees the label.
+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 may truncate (~30k chars per read); 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
+
+Manage the persistent PTY session. One-shot style output, but stable: every command returns synchronously with exit, cwd, and an env delta.
 
-oneshot: stateless bash -lc, stdout/stderr separate, exit code verbatim; the endpoint needs bash only (no Python). A POSIX wrapper reaps backgrounded children on completion and kills the whole group on timeout/cancel — they never outlive the call or hold the channel. pty: one shell per (agent, target); cwd/env survive, streams merge, Ctrl-C interrupts without killing, idle reap after 600s.
+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.
 
-Files — {action:"copy" | "rsync", src:"[target:]abs", dst:"[target:]abs", argv:["-a"]}: argv tokens pass verbatim before src/dst — no whitelist, no forced defaults (dry run = pass "--dry-run" yourself); the CLI's own exit code and stderr come back in the receipt. copy: local↔SSH scp; SSH↔SSH scp -3 through the origin (identities stay local); docker cp; incus file push/pull; any other pair = two commands with origin staging (per-half options via pullArgv/pushArgv, exclusive with argv); scp -R refused; success is NOT independently verified; verify/mkdir only on the Hub↔local lane. rsync: local↔SSH, or SSH↔SSH with one protocol conversation between the peers (real delta; forwarding denied → honest error, never full copy). rsync src trailing slash copies contents, no slash the directory itself.
+remote { "action": "add", "spawn": "ssh -t pc ssh -t dev4", "target": "pty:dev4via" }
 
-Output: pty tails at ~30k chars ("[truncated: …]" header) — redirect bulk output to a file. Hard retention 4,000,000 UTF-16 units per stream (Hub 4MiB bytes); outputStats reports the rest; restart cannot recover discarded output. stdin feeds the command; timeout (seconds) interrupts then kills. run_in_background:true (oneshot) → jobId for job_output/job_kill. Native transport errors pass through verbatim — self-correct from them.`;
+[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"] }`;
+/** action 是唯一派发维度：每个动词声明自己的字段集，超出即报错（不做在场推断、不留别名）。 */
+const ACTION_PARAMS = {
+	exec: new Set([
+		"action",
+		"target",
+		"cmd",
+		"stdin",
+		"scriptPath",
+		"timeout",
+		"run_in_background"
+	]),
+	add: new Set([
+		"action",
+		"target",
+		"ssh",
+		"spawn"
+	]),
+	status: new Set(["action", "target"]),
+	close: new Set([
+		"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",
+	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"
+};
+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)");
+	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`);
+	for (const key of Object.keys(args)) if (!allowed.has(key)) throw new Error(`[E_PARAMS] remote: "${key}" does not belong to action "${action}" — ${ACTION_HINT[action]}`);
+	const sessionKey = ENV.getSessionKey(exec);
+	const hasTarget = typeof args.target === "string" && args.target.length > 0;
+	const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
+	if (action === "status") {
+		if (!hasTarget) return {
+			kind: "roster",
+			text: await ENV.driver.roster({ sessionKey }),
+			exit: null,
+			durationMs: 0
+		};
+		return {
+			kind: "status",
+			text: await ENV.driver.status(args.target, { sessionKey }),
+			exit: null,
+			durationMs: 0
+		};
+	}
+	if (action === "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);
+		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"}`,
+			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
+		};
+	}
+	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;
+		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 (action === "add") {
+		const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
+		if (args.spawn !== void 0 && !hasSpawn) throw new Error("[E_PARAMS] remote: add: spawn must be a non-empty command string");
+		if (args.ssh === void 0 && !hasSpawn) throw new Error("[E_PARAMS] remote: action \"add\" registers a BYO endpoint — pass ssh:{host,...} (identity) or spawn:\"<command>\" (PTY), exactly one");
+		if (args.ssh !== void 0 && hasSpawn) throw new Error("[E_PARAMS] remote: add: ssh and spawn are two different BYO entry points — pass one, not both");
+		const r$1 = await ENV.driver.call({
+			...hasTarget ? { target: args.target } : {},
+			...args.ssh === void 0 ? {} : { ssh: args.ssh },
+			...hasSpawn ? { spawn: args.spawn } : {},
+			cmd: ""
+		}, { sessionKey });
+		const v$1 = workbenchValue(r$1);
+		v$1.created = true;
+		if (!hasSpawn) v$1.notice = `registered — address it as ${r$1.session ?? r$1.target} from now on (the label, id and ssh alias all work)`;
+		return v$1;
+	}
+	if (!hasTarget) throw new Error("[E_PARAMS] remote: action \"exec\" requires target — a machine (ssh:dev4, docker:corti, hub:<m4>, a pool name) or a PTY session (pty:<id|label>, a bare label, or <machine>:pty[:label] to create one). Status probes and the roster live under action \"status\".");
+	const target = args.target;
+	const ptyTarget = /^pty:/.test(target) || /:pty(:|$)/.test(target);
+	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.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");
+		const lane = await ENV.driver.preparePtyLane({
+			target: args.target,
+			cmd: args.cmd,
+			scriptPath: args.scriptPath,
+			stdin: args.stdin,
+			timeout: args.timeout
+		}, { sessionKey });
+		let jobId;
+		try {
+			jobId = startRemoteJob(jobs, lane !== void 0 ? lane.input : {
+				target: args.target,
+				cmd: args.cmd,
+				scriptPath: args.scriptPath,
+				stdin: args.stdin,
+				timeout: args.timeout
+			}, exec, ENV.driver);
+		} catch (error) {
+			lane?.cleanup();
+			throw error;
+		}
+		const where = lane === void 0 ? "" : ` on ${lane.session}${lane.label !== void 0 ? ` (${lane.label})` : ""} (${lane.connection})`;
+		return {
+			kind: "job",
+			jobId,
+			exit: null,
+			durationMs: 0,
+			text: `Started ${jobId}${where}. Use job_output to read and job_kill to cancel; completion is reported by the host.`,
+			...lane !== void 0 ? {
+				commandId: jobId,
+				session: lane.session,
+				connection: lane.connection,
+				...lane.label !== void 0 ? { label: lane.label } : {}
+			} : {}
+		};
+	}
+	const r = await ENV.driver.call({
+		target: args.target,
+		cmd: args.cmd,
+		scriptPath: args.scriptPath,
+		stdin: args.stdin,
+		timeout: args.timeout
+	}, { sessionKey });
+	const v = workbenchValue(r);
+	if (r.running === true && r.ptyJob !== void 0) {
+		const jobs = exec.agent?.ctx.get("jobs");
+		if (jobs) {
+			const jobId = adoptRunningPtyJob(jobs, exec, `${r.target}: ${args.cmd}`, r.ptyJob);
+			v.jobId = jobId;
+			v.running = true;
+			if (r.commandId !== void 0 && jobId !== r.commandId) ENV.driver.attachPtyJob(r.commandId, jobId, sessionKey);
+		} else {
+			r.ptyJob.interrupt();
+			v.notice = "The command outlived its synchronous wait and no jobs service is available to poll it, so it was interrupted. Use run_in_background:true for long commands.";
+		}
+	}
+	return v;
+}
 function createRemoteTool(driver, opts = {}) {
-	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY$1);
 	const tool = defineTool({
 		name: "remote",
 		description: REMOTE_TOOL_DESCRIPTION,
 		parameters: {
 			action: {
 				type: "string",
-				enum: ["copy", "rsync"],
-				description: "Optional file action; omit for execution/status/roster."
+				enum: [
+					"exec",
+					"add",
+					"status",
+					"close",
+					"input"
+				],
+				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."
 			},
-			src: {
+			target: {
 				type: "string",
-				description: "copy/rsync source [target:]absolute path; rsync retains trailing-slash semantics"
+				description: "exec: required. A machine (bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>), 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)."
 			},
-			dst: {
+			cmd: {
 				type: "string",
-				description: "copy/rsync destination [target:]absolute path"
-			},
-			argv: {
-				type: "array",
-				items: { type: "string" },
-				description: "Ordered native CLI options and values for one-command routes (e.g. rsync [\"-a\",\"--partial\",\"--dry-run\"], scp [\"-p\"], docker cp [\"-a\"], incus file push/pull). One element = one argv token, appended verbatim before src/dst; no shell parsing, no whitelist, no forced defaults — unknown options fail in the native CLI itself. rsync only (SSH endpoints): explicit -e/--rsh overrides the tool's SSH wiring. Two-segment cross-endpoint copy uses pullArgv/pushArgv instead."
+				description: "exec: one raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Required unless scriptPath is given."
 			},
-			pullArgv: {
-				type: "array",
-				items: { type: "string" },
-				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
-			},
-			pushArgv: {
-				type: "array",
-				items: { type: "string" },
-				description: "Options for the PUSH half (origin staging → destination endpoint) of a two-command cross-endpoint copy. Mutually exclusive with argv; must be paired with pullArgv. Only options valid for the push half's CLI."
+			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."
 			},
-			verify: {
-				type: "boolean",
-				description: "copy only, Hub↔local↔local staged lane only: independent SHA-256 verification (default true). Native CLI routes do not verify and report that fact."
+			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."
 			},
-			mkdir: {
-				type: "boolean",
-				description: "copy only, Hub↔local↔local staged lane only: create missing destination parents (default true). Native CLI routes let the CLI decide."
+			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)."
 			},
 			run_in_background: {
 				type: "boolean",
-				description: "Oneshot only: return a native jobId immediately, read with job_output, cancel with job_kill; output is available while running. Requires official jobs service/controller."
-			},
-			target: {
-				type: "string",
-				description: "Single entry point. byossh:<label> reuses this Agent-scoped registered SSH identity (pass ssh on first call; no cmd registers only). Bare name / IP / domain matches in order: ssh config, then docker, then incus, then a live pty label (a collision goes to the earlier source). \"byop:<label>\" / \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a channel. For \"byop:<label>\", pass spawn the first time to create it and omit spawn afterwards to reuse it. Omit cmd → status probe."
+				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."
 			},
 			ssh: {
 				type: "object",
-				description: "Only for byossh:<label>: register origin-side connection; omit on reuse. No inline keys or arbitrary SSH options.",
+				description: "add: BYO ssh identity to register into the pool (no dialing). Later exec calls address the returned label. No inline keys or arbitrary SSH options; nothing is persisted — a new Agent registers again.",
 				additionalProperties: false,
 				properties: {
 					host: {
@@ -3031,28 +4684,11 @@ function createRemoteTool(driver, opts = {}) {
 			},
 			spawn: {
 				type: "string",
-				description: "Only valid together with a \"byop:<label>\" target, and required the first time that label is created: the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). It is not retained — pass it again if the label answers [E_NO_SESSION]. Requires cmd; mode is locked to pty; nested hops are dumb pipes (only the innermost bash frames)."
-			},
-			cmd: {
-				type: "string",
-				description: "One raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Omit with target → status probe; omit everything → roster."
-			},
-			script: {
-				type: "string",
-				description: "LOCAL absolute script path. Read before any dialing, sent literally over stdin to fixed bash -s. Oneshot only; cannot combine with cmd, stdin, spawn, pty mode or byop target. Hub inline cmd remains limited to 4096; script body is not argv."
-			},
-			mode: {
-				type: "string",
-				enum: ["oneshot", "pty"],
-				description: "'oneshot' (default): stateless `bash -lc`, stdout/stderr separate, exit code is the process's own. 'pty': one persistent shell per (agent, target), cwd/env survive, streams merge, idle TTL 600s. A \"byop:<label>\" target locks mode to 'pty'."
-			},
-			stdin: {
-				type: "string",
-				description: "Input fed to the command. oneshot: piped to stdin. pty: written right after the command line (REPL-style) — only helps commands that read stdin there. Requires cmd."
+				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)."
 			},
-			timeout: {
-				type: "number",
-				description: "Per-command timeout in seconds (default 120, row-configurable). pty: Ctrl-C first, then kill; an interrupt does not kill the session."
+			force: {
+				type: "boolean",
+				description: "close only: default false — a session with a running job is refused (job_kill it first). true = kill the group and close in one step; the receipt lists what was killed."
 			}
 		},
 		output: {
@@ -3068,8 +4704,8 @@ function createRemoteTool(driver, opts = {}) {
 							"status",
 							"roster",
 							"job",
-							"copy",
-							"rsync"
+							"close",
+							"input"
 						]
 					},
 					text: {
@@ -3087,8 +4723,49 @@ function createRemoteTool(driver, opts = {}) {
 					truncated: { type: "integer" },
 					outputStats: { type: "json" },
 					outputStatsUnavailable: { type: "boolean" },
-					session: { type: "string" },
-					notice: { type: "string" }
+					session: {
+						type: "string",
+						description: "pty session id, e.g. pty:pty-7k2m"
+					},
+					label: { type: "string" },
+					connection: {
+						type: "string",
+						description: "underlying connection: ssh:dev4 / docker:c / incus:x / hub:m4 / BYOP"
+					},
+					byoTag: { type: "string" },
+					commandId: {
+						type: "string",
+						description: "ledger key; equals the jobId whenever a job exists"
+					},
+					writtenBytes: {
+						type: "integer",
+						description: "input: UTF-8 bytes actually written; confirms the write, not the program response"
+					},
+					envDelta: {
+						type: "json",
+						description: "names only: {added,changed,removed}"
+					},
+					created: { type: "boolean" },
+					notice: { type: "string" },
+					runner: {
+						type: "string",
+						description: "oneshot supervision path: superd-run <ver> (<triple>), posix-shim, or hub-lease (peer hub server supervises natively)"
+					},
+					running: { type: "boolean" },
+					ttlSec: { type: "integer" },
+					closed: {
+						type: "boolean",
+						description: "close: true = the session is gone now"
+					},
+					reason: {
+						type: "string",
+						description: "close: not-found / already-closed-or-reaped"
+					},
+					killed: {
+						type: "array",
+						items: { type: "string" },
+						description: "close force: the running commandIds that were killed"
+					}
 				}
 			},
 			render: (_args, value) => [{
@@ -3097,174 +4774,257 @@ function createRemoteTool(driver, opts = {}) {
 			}]
 		},
 		async execute(args, exec) {
-			if (args.action === "copy" || args.action === "rsync") {
-				if (!args.src || !args.dst) throw new Error(`${args.action} requires src and dst absolute endpoints`);
-				if ([
-					args.cmd,
-					args.script,
-					args.stdin,
-					args.spawn,
-					args.ssh,
-					args.target,
-					args.mode,
-					args.timeout,
-					args.run_in_background
-				].some((value) => value !== void 0)) throw new Error(`${args.action} cannot be combined with execution/PTY/job arguments; register byossh separately first`);
-				for (const legacy of [
-					"dryRun",
-					"delete",
-					"excludes",
-					"preserve"
-				]) if (args[legacy] !== void 0) throw new Error(`${legacy} was removed: pass native options through argv instead (e.g. ${legacy === "dryRun" ? "\"--dry-run\"" : legacy === "delete" ? "\"--delete\"" : legacy === "excludes" ? "\"--exclude=<pattern>\"" : "\"-a\" / \"-r\""})`);
-				if (args.action === "rsync") {
-					if (args.pullArgv !== void 0 || args.pushArgv !== void 0) throw new Error("rsync takes argv only; pullArgv/pushArgv are copy-only fields");
-					if ([args.verify, args.mkdir].some((value) => value !== void 0)) throw new Error("rsync cannot be combined with copy verify/mkdir options; the Hub/local staged lane is copy-only");
-					const start = Date.now();
-					const receipt$1 = await driver.rsync({
-						src: args.src,
-						dst: args.dst,
-						...args.argv === void 0 ? {} : { argv: args.argv }
-					}, exec.signal, { sessionKey: getSessionKey(exec) });
-					if (receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
-					return {
-						kind: "rsync",
-						text: JSON.stringify(receipt$1),
-						receipt: receipt$1,
-						exit: receipt$1.exit,
-						durationMs: Date.now() - start
-					};
-				}
-				const receipt = await driver.copy({
-					src: args.src,
-					dst: args.dst,
-					...args.verify === void 0 ? {} : { verify: args.verify },
-					...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
-					...args.argv === void 0 ? {} : { argv: args.argv },
-					...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
-					...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
-				}, exec.signal, { sessionKey: getSessionKey(exec) });
-				return {
-					kind: "copy",
-					text: JSON.stringify(receipt),
-					receipt,
-					exit: null,
-					durationMs: 0
-				};
-			}
-			if ([
-				args.src,
-				args.dst,
-				args.argv,
-				args.pullArgv,
-				args.pushArgv,
-				args.verify,
-				args.mkdir
-			].some((value) => value !== void 0)) throw new Error("file fields require action copy or rsync");
-			const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
-			const hasTarget = typeof args.target === "string" && args.target.length > 0;
-			const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
-			if (args.mode !== void 0 && args.mode !== "oneshot" && args.mode !== "pty") throw new Error(`[E_BAD_MODE] remote: mode must be 'oneshot' or 'pty' (got ${JSON.stringify(args.mode)})`);
-			if (args.ssh !== void 0 && (!args.target?.startsWith("byossh:") || hasSpawn)) throw new Error("[E_SSH_PARAMS] remote: ssh requires a byossh:<label> target; spawn is only for byop:<label>");
-			if (args.run_in_background) {
-				if (!hasCmd && args.script === void 0) throw new Error("remote: background requires cmd or script");
-				if (args.mode === "pty" || hasSpawn || args.target?.startsWith("byop:")) throw new Error("remote: background requires oneshot; PTY and BYO-PTY are unsupported");
-				const jobs = exec.agent?.ctx.get("jobs");
-				if (!jobs) throw new Error("remote: background requires the official DSH jobs service and job_output/job_kill controller; foreground execution remains available");
-				const jobId = startRemoteJob(jobs, {
-					target: args.target,
-					cmd: args.cmd,
-					script: args.script,
-					ssh: args.ssh,
-					stdin: args.stdin,
-					mode: "oneshot",
-					timeout: args.timeout
-				}, exec, driver);
-				return {
-					kind: "job",
-					jobId,
-					text: `Started ${jobId}. Use job_output to read and job_kill to cancel; completion is reported by the host.`,
-					exit: null,
-					durationMs: 0
-				};
-			}
-			if (!hasCmd && args.script === void 0) {
-				if (args.stdin !== void 0) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd — status probes take no input");
-				if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn is an exec channel — pass cmd (there is nothing to probe for BYO-PTY)");
-				if (args.ssh !== void 0) return {
-					kind: "status",
-					text: driver.registerSsh(args.target, args.ssh),
-					exit: null,
-					durationMs: 0
-				};
-				if (!hasTarget) return {
-					kind: "roster",
-					text: await driver.roster({ sessionKey: getSessionKey(exec) }),
-					exit: null,
-					durationMs: 0
-				};
-				return {
-					kind: "status",
-					text: await driver.status(args.target, { sessionKey: getSessionKey(exec) }),
-					exit: null,
-					durationMs: 0
-				};
-			}
-			const r = await driver.call({
-				target: args.target,
-				spawn: args.spawn,
-				ssh: args.ssh,
-				cmd: args.cmd,
-				script: args.script,
-				mode: args.mode === "oneshot" || args.mode === "pty" ? args.mode : void 0,
-				stdin: args.stdin,
-				timeout: args.timeout
-			}, { sessionKey: getSessionKey(exec) });
-			const v = {
-				kind: "exec",
-				text: r.stdout,
-				exit: r.exit,
-				durationMs: r.durationMs
-			};
-			if (r.cwd !== null) v.cwd = r.cwd;
-			if (r.stderr !== void 0) v.stderr = r.stderr;
-			if (r.timedOut) v.timedOut = true;
-			if (r.reconnected) v.reconnected = true;
-			if (r.truncated !== void 0) v.truncated = r.truncated;
-			if (r.outputStats !== void 0) v.outputStats = r.outputStats;
-			if (r.outputStatsUnavailable) v.outputStatsUnavailable = true;
-			if (r.session !== void 0) v.session = r.session;
-			if (r.notice !== void 0) v.notice = r.notice;
-			return v;
+			return remoteExecute({
+				driver,
+				getSessionKey
+			}, args, exec);
 		}
 	});
 	const description = tool.description;
 	Object.defineProperty(tool, "description", {
 		enumerable: true,
-		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self). {} includes the Hub directory even when empty. Uses authenticated Hub HTTP oneshot / persistent WS PTY; no SSH alias needed. Hub failures never fall back to SSH." : "")
+		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self; the roster lists them). Hub failures never fall back to SSH.\n- hub:<m4> oneshot: the peer hub server is the runner itself — bash -lc in a detached group, TERM→2s→KILL cleanup; the receipt runner field says \"hub-lease\" (the superd-run helper is a dumb-pipe artifact, never uploaded over the Hub). 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." : "")
 	});
 	return tool;
 }
+/** RemoteCallResult → RemoteToolValue（pty 工作台字段 + 既有字段）。 */
+function workbenchValue(r) {
+	const v = {
+		kind: "exec",
+		text: r.stdout,
+		exit: r.exit,
+		durationMs: r.durationMs
+	};
+	if (r.cwd !== null && r.cwd !== void 0) v.cwd = r.cwd;
+	if (r.stderr !== void 0) v.stderr = r.stderr;
+	if (r.timedOut) v.timedOut = true;
+	if (r.reconnected) v.reconnected = true;
+	if (r.truncated !== void 0) v.truncated = r.truncated;
+	if (r.outputStats !== void 0) v.outputStats = r.outputStats;
+	if (r.outputStatsUnavailable) v.outputStatsUnavailable = true;
+	if (r.session !== void 0) v.session = r.session;
+	if (r.label !== void 0) v.label = r.label;
+	if (r.connection !== void 0) v.connection = r.connection;
+	if (r.byoTag !== void 0) v.byoTag = r.byoTag;
+	if (r.commandId !== void 0) v.commandId = r.commandId;
+	if (r.envDelta !== void 0) v.envDelta = r.envDelta;
+	if (r.created === true) v.created = true;
+	if (r.notice !== void 0) v.notice = r.notice;
+	if (r.runner !== void 0) v.runner = r.runner;
+	if (r.ttlSec !== void 0) v.ttlSec = r.ttlSec;
+	return v;
+}
+function renderEnvDelta(d) {
+	const bits = [];
+	if (d.added.length > 0) bits.push(`+${d.added.join(",+")}`);
+	if (d.changed.length > 0) bits.push(`~${d.changed.join(",~")}`);
+	if (d.removed.length > 0) bits.push(`-${d.removed.join(",-")}`);
+	return bits.length > 0 ? bits.join(" ") : void 0;
+}
 function renderValue(v) {
-	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "copy" || v.kind === "rsync") return v.text;
+	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "close" || v.kind === "input") 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);
+	if (v.created === true && v.session !== void 0) parts.push(`[session created — address it as ${v.session}]`);
 	parts.push(v.text);
 	const secs = ((v.durationMs ?? 0) / 1e3).toFixed(1);
 	const markers = [];
+	if (typeof v.session === "string" && v.session.length > 0) markers.push(`${v.session}${typeof v.label === "string" && v.label.length > 0 ? ` (${v.label})` : ""}${v.byoTag !== void 0 ? ` (${v.byoTag})` : ""}`);
+	if (typeof v.connection === "string" && v.connection.length > 0 && v.session !== void 0) markers.push(`conn ${v.connection}`);
+	if (typeof v.commandId === "string" && v.commandId.length > 0) markers.push(`cmd ${v.commandId}`);
+	if (typeof v.cwd === "string" && v.cwd.length > 0) markers.push(`cwd ${v.cwd}`);
+	const envTag = v.envDelta !== void 0 ? renderEnvDelta(v.envDelta) : void 0;
+	if (envTag !== void 0) markers.push(`env ${envTag}`);
+	if (typeof v.ttlSec === "number") markers.push(`idle-left ~${Math.max(1, Math.round(v.ttlSec / 60))}m`);
+	if (typeof v.runner === "string" && v.runner.length > 0) markers.push(`runner ${v.runner}`);
 	if (v.timedOut === true) markers.push("interrupted");
+	markers.push(`exit ${v.exit}`);
+	markers.push(`${secs}s`);
+	if (v.running === true) markers.push(`still running — poll job_output${v.jobId !== void 0 ? ` ${v.jobId}` : ""}`);
 	if (v.truncated !== void 0) markers.push(`truncated, ${v.outputStatsUnavailable ? "returned peer tail" : "original"} ${v.truncated} ${v.outputStats?.stdout.unit === "bytes" ? "bytes" : "chars"}`);
 	if (v.outputStatsUnavailable) markers.push("peer output totals/retention unavailable; returned tail only");
-	const suffix = markers.length > 0 ? ` · ${markers.join(" · ")}` : "";
-	const cwdTag = typeof v.cwd === "string" && v.cwd.length > 0 ? ` · cwd ${v.cwd}` : "";
-	const sessionTag = typeof v.session === "string" && v.session.length > 0 ? ` · ${v.session}` : "";
-	parts.push(`[exit ${v.exit} · ${secs}s${suffix}${cwdTag}${sessionTag}]`);
+	parts.push(`[${markers.join(" · ")}]`);
+	if (v.runner === "posix-shim" && (v.exit !== null && v.exit !== 0 || v.timedOut === true)) parts.push("note: this oneshot ran through the POSIX fallback on this target; PTY lanes use an independent lane and may still work here");
 	if (v.stderr !== void 0 && v.stderr.length > 0) parts.push("[stderr]", v.stderr);
 	return parts.join("\n");
 }
 
+//#endregion
+//#region src/remote/transfer-tool.ts
+const NO_SESSION_KEY = "remote:no-session";
+/**
+* The model-visible surface of the `remote_transfer` tool (split out of
+* `remote`, 2026-10-25). ONE template literal — no backticks, no "${".
+*/
+const TRANSFER_TOOL_DESCRIPTION = `File transfer between any two supported endpoints. Every call declares its mode:
+  mode:"copy"   → tree copy. Native CLI per endpoint (scp for ssh, docker cp, incus file push/pull), a plain tree copy when both ends are local, and the Hub binary lane when a Hub machine is involved. Directories copy recursively; exit codes are authoritative.
+  mode:"rsync"  → rsync over SSH only: at least one endpoint remote SSH, the other local or SSH (both remote legs tunnel through this machine; identities never leave it). Hub and container endpoints are rejected — no silent copy fallback. Trailing slashes keep rsync semantics.
+
+Endpoints are "[target:]absolute path". No target = the machine running this Agent. Targets are the same unified pool remote uses: a bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>. Examples: "/srv/app", "ssh:dev4:/srv/app", "docker:corti:/var/lib/x", "hub:m4:/srv". A path is never guessed: both operands must be absolute.
+
+Native CLI options travel through argv verbatim — one element = one token, appended before src/dst, no shell parsing and no whitelist: rsync ["-a","--partial"], scp ["-p","-r"], docker cp ["-a","-L"], incus file push ["--recursive"]. Cross-endpoint copies that need two commands (SSH↔Docker, SSH↔Incus, Docker↔Incus) take pullArgv plus pushArgv instead of argv. rsync is a single SSH command, so it takes argv only; an explicit -e/--rsh overrides the wiring.
+
+Options: verify (copy only) — the Hub↔local staged lane computes independent SHA-256 digests by default and verify:false skips them; native CLI routes have no independent hash tier, so verify is rejected there (self-verify through a oneshot digest command). mkdir (copy only, default true) — one best-effort pre-hop creates the destination PARENT directory; the operand itself is never pre-created, so each CLI's own layout semantics stay byte-identical.
+
+Failures are loud: a non-zero native exit throws with the receipt instead of returning a normal-looking result. The receipt stays in the receipt field (route, exits, verification, bytes/entries, cleanup); text is one formatted line. For checksum-grade verification of a native route, run a digest command through remote oneshot or PTY instead of trusting the copy receipt.`;
+const KNOWN_PARAMS = new Set([
+	"mode",
+	"src",
+	"dst",
+	"argv",
+	"pullArgv",
+	"pushArgv",
+	"verify",
+	"mkdir"
+]);
+async function transferExecute(ENV, args, exec) {
+	for (const key of Object.keys(args)) if (!KNOWN_PARAMS.has(key)) throw new Error(`remote_transfer: unknown parameter "${key}" — this surface has no legacy aliases; pass native CLI options through argv instead`);
+	if (args.mode !== "copy" && args.mode !== "rsync") throw new Error(`[E_PARAMS] remote_transfer: mode is required — "copy" (tree copy through each endpoint's native CLI or the Hub lane) or "rsync" (SSH only)`);
+	if (typeof args.src !== "string" || args.src.length === 0 || typeof args.dst !== "string" || args.dst.length === 0) throw new Error(`[E_PARAMS] remote_transfer: ${args.mode} requires src and dst absolute endpoints`);
+	const sessionKey = ENV.getSessionKey(exec);
+	if (args.mode === "rsync") {
+		if (args.pullArgv !== void 0 || args.pushArgv !== void 0) throw new Error("remote_transfer: rsync takes argv only; pullArgv/pushArgv are copy-only fields");
+		if (args.verify !== void 0 || args.mkdir !== void 0) throw new Error("remote_transfer: rsync cannot be combined with copy verify/mkdir options; the Hub/local staged lane is copy-only");
+		const start$1 = Date.now();
+		const receipt$1 = await ENV.driver.rsync({
+			src: args.src,
+			dst: args.dst,
+			...args.argv === void 0 ? {} : { argv: args.argv }
+		}, exec.signal, { sessionKey });
+		if (receipt$1.ok === false || receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
+		const durationMs$1 = Date.now() - start$1;
+		return {
+			kind: "rsync",
+			text: formatTransferLine("rsync", receipt$1, durationMs$1),
+			receipt: receipt$1,
+			exit: receipt$1.exit,
+			durationMs: durationMs$1
+		};
+	}
+	const start = Date.now();
+	const receipt = await ENV.driver.copy({
+		src: args.src,
+		dst: args.dst,
+		...args.verify === void 0 ? {} : { verify: args.verify },
+		...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
+		...args.argv === void 0 ? {} : { argv: args.argv },
+		...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
+		...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
+	}, exec.signal, { sessionKey });
+	const asReceipt = receipt;
+	const exits = asReceipt.exits ?? [];
+	if (asReceipt.ok === false || exits.some((code) => code !== 0)) throw new Error(JSON.stringify(receipt));
+	const durationMs = Date.now() - start;
+	return {
+		kind: "copy",
+		text: formatTransferLine("copy", receipt, durationMs),
+		receipt,
+		exit: exits.length > 0 ? 0 : null,
+		durationMs
+	};
+}
+function createRemoteTransferTool(driver, opts = {}) {
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	return defineTool({
+		name: "remote_transfer",
+		description: TRANSFER_TOOL_DESCRIPTION,
+		parameters: {
+			mode: {
+				type: "string",
+				enum: ["copy", "rsync"],
+				required: true,
+				description: "Required. copy = tree copy through each endpoint's native CLI, or the Hub binary lane; rsync = SSH only (argv only, no verify/mkdir)."
+			},
+			src: {
+				type: "string",
+				description: "Source [target:]absolute path. No target = the machine running this Agent."
+			},
+			dst: {
+				type: "string",
+				description: "Destination [target:]absolute path. No target = the machine running this Agent."
+			},
+			argv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Ordered native CLI options and values for one-command routes (e.g. rsync [\"-a\",\"--partial\",\"--dry-run\"], scp [\"-p\",\"-r\"], docker cp [\"-a\",\"-L\"], incus file push/pull). One element = one argv token, appended verbatim before src/dst; no shell parsing, no whitelist, no forced defaults — unknown options fail in the native CLI itself. rsync only (SSH endpoints): explicit -e/--rsh overrides the tool's SSH wiring. docker cp: pass -L to follow symlinks (a symlink source like /etc/os-release fails without it). Two-segment cross-endpoint copy uses pullArgv/pushArgv instead."
+			},
+			pullArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
+			},
+			pushArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PUSH half (origin staging → destination endpoint) of a two-command cross-endpoint copy. Mutually exclusive with argv; must be paired with pullArgv."
+			},
+			verify: {
+				type: "boolean",
+				description: "copy only. Receipts name the verification tier actually performed (D1=A): native CLI routes are \"native-exit-only\" (no independent check — self-verify via oneshot digest commands when needed); the Hub↔local staged lane computes independent SHA-256 digests by default and verify:false skips them (\"not-applicable\"). No hash tier exists on native routes."
+			},
+			mkdir: {
+				type: "boolean",
+				description: "copy only, all routes. Default true: before transfer, one best-effort exec pre-hop ensures the destination's PARENT directory exists (the operand itself is never pre-created — each CLI's own layout semantics stay byte-identical). Receipt created field: true (parent created this call) / false (already existed) / \"n-a\" (skipped or pre-hop unavailable, e.g. docker exec on a stopped container — the native CLI then reports the real error itself). false skips the pre-hop."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						enum: ["copy", "rsync"]
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					receipt: { type: "json" },
+					exit: { oneOf: [{ type: "integer" }, { type: "null" }] },
+					durationMs: { type: "integer" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args, exec) {
+			return transferExecute({
+				driver,
+				getSessionKey
+			}, args, exec);
+		}
+	});
+}
+/** S8 (2026-10-17): copy/rsync render as one formatted line; the full receipt
+* stays in the receipt field — raw-JSON dumps are gone from text. */
+function formatTransferLine(mode, receipt, durationMs) {
+	const r = receipt;
+	const parts = [];
+	if (r.ok === false) parts.push(`✗ ${r.reason ?? "failed"}`);
+	parts.push(`${mode} ${r.src} → ${r.dst}`);
+	if (r.route !== void 0 && r.route !== "") parts.push(`route ${r.route}`);
+	if (r.exits !== void 0) parts.push(`exits [${r.exits.join(",")}]`);
+	else if (r.exit !== void 0) parts.push(`exit ${r.exit}`);
+	if (r.verification !== void 0) parts.push(`verification ${r.verification}`);
+	if (r.created === true) parts.push("created yes");
+	else if (r.created === false) parts.push("created pre-existing");
+	else if (r.created === "n-a") parts.push("created n-a");
+	if (r.cleanup !== void 0 && r.cleanup !== "none-required") parts.push(`cleanup ${r.cleanup}`);
+	if (typeof r.bytes === "number") parts.push(`${r.bytes} bytes / ${r.entries} entries`);
+	parts.push(`${(durationMs / 1e3).toFixed(1)}s`);
+	if (r.note !== void 0 && r.note.length > 0) parts.push(`(${r.note})`);
+	return parts.join(" · ");
+}
+
 //#endregion
 //#region src/remote/agent-registration.ts
+/** The pair a row contributes: execution/PTY and file transfer are separate tools. */
+const TOOL_NAMES = ["remote", "remote_transfer"];
 /** Host listeners attempt once per official creation edge, never on vacancy. */
 function installAgentRemote(ctx, config) {
 	return ctx.on("agent/created", ({ agent }) => {
@@ -3274,12 +5034,14 @@ function installAgentRemote(ctx, config) {
 			...config,
 			getHub: () => agent.ctx.get("superdRemoteTransport")
 		});
-		let unregister;
+		const registered = [];
 		try {
-			unregister = tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id }));
+			registered.push(tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id })));
+			registered.push(tools.register(createRemoteTransferTool(driver, { getSessionKey: () => agent.id })));
 		} catch (error) {
+			for (const undo of registered.splice(0)) undo();
 			driver.dispose();
-			if (error instanceof Error && error.message === "tool \"remote\" is already registered in this scope" && tools.get("remote", agent) !== void 0) return;
+			if (TOOL_NAMES.find((name$1) => error instanceof Error && error.message === `tool "${name$1}" is already registered in this scope` && tools.get(name$1, agent) !== void 0) !== void 0) return;
 			throw error;
 		}
 		const stopService = agent.ctx.on("internal/service", (name$1) => {
@@ -3291,7 +5053,7 @@ function installAgentRemote(ctx, config) {
 		const cleanup = () => {
 			if (disposal) return disposal;
 			disposal = driver.dispose();
-			unregister();
+			for (const undo of registered.splice(0)) undo();
 			stopService();
 			ownerUndo?.();
 			agentUndo?.();
@@ -3347,11 +5109,11 @@ const name = "dashr-remote";
 const inject = [];
 const Config = Schema.object({
 	execTimeoutSec: Schema.natural().min(1).default(120),
-	idleTtlSec: Schema.natural().min(1).default(600),
+	idleTtlSec: Schema.natural().min(1).default(REMOTE_PTY_IDLE_TTL_SEC),
 	maxOutputChars: Schema.natural().min(1).default(3e4)
 }).default({
 	execTimeoutSec: 120,
-	idleTtlSec: 600,
+	idleTtlSec: REMOTE_PTY_IDLE_TTL_SEC,
 	maxOutputChars: 3e4
 });
 /** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
@@ -3366,4 +5128,4 @@ var plugin_default = {
 };
 
 //#endregion
-export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, SshTargets, Utf16TailRing, apply, checkAbsolute, checkSelection, plugin_default as default, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };
+export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, PtySession, Utf16TailRing, apply, buildHubPtyArgv, checkAbsolute, checkSelection, plugin_default as default, hubPtyAssets, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob, tailWindow };