better-dsh 0.3.2 → 0.3.3

package/lib/remote/plugin.js

@@ -1,4 +1,5 @@
 import { t as Schema } from "../lib.js";
+import { createRequire } from "node:module";
 import { Context } from "@deepseek-ai/cordis";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { constants, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
@@ -11,6 +12,7 @@ import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, rename
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { createConnection, createServer } from "node:net";
+import { Buffer as Buffer$1 } from "node:buffer";
 
 //#region src/remote/archive.ts
 const FILE_FRAME_BYTES = 64 * 1024;
@@ -1835,6 +1837,23 @@ 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. */
@@ -1955,22 +1974,25 @@ function stripAnsi(s) {
 function normalizePtyText(s) {
 	return stripAnsi(s).replace(/\r\n/g, "\n").replace(/\r/g, "");
 }
-function tailWindow(text, cap, stats) {
-	let tail = text.slice(-cap);
-	if (tail.charCodeAt(0) >= 56320 && tail.charCodeAt(0) <= 57343) tail = tail.slice(1);
-	const returned = stats?.unit === "bytes" ? Buffer.byteLength(tail) : tail.length;
-	const total = stats?.total ?? text.length;
-	const updated = stats === void 0 ? {} : { stats: {
+/** 0.3.2-e：自有 30K 返回窗口已删（原生 agent runtime 的 spill/输出保护接管模型上下文
+* 尺寸）。本 helper 只做 retention 披露：ring 留存（4M UTF-16 / 4MiB bytes）未驱逐时
+* 全量透传（returned=retained，无 banner）；驱逐（dropped>0，仅 >4M 输出发生）时打一行
+* banner 且 truncated=原始总量。text 已是 ring 尾部，不再二次裁剪。 */
+function disclose(text, stats) {
+	if (stats === void 0) return { text };
+	const returned = stats.retained;
+	const updated = { stats: {
 		...stats,
 		returned
 	} };
-	if (total <= returned) return {
-		text: tail,
+	if (stats.dropped <= 0) return {
+		text,
 		...updated
 	};
+	const unit = stats.unit === "bytes" ? "bytes" : "chars";
 	return {
-		text: `[truncated: showing last ${returned} of ${total} ${stats?.unit === "bytes" ? "bytes" : "chars"}${stats !== void 0 && stats.dropped > 0 ? `; retained ${stats.retained}, dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === "bytes" ? "bytes" : "UTF-16 code units"}` : ""}]\n${tail}`,
-		truncated: total,
+		text: `[retention tail: showing last ${stats.retained} of ${stats.total} ${unit}; dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === "bytes" ? "bytes" : "UTF-16 code units"}]\n${text}`,
+		truncated: stats.total,
 		...updated
 	};
 }
@@ -2114,13 +2136,15 @@ const summaryOf = (cmd) => {
 };
 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 = [];
@@ -2128,6 +2152,8 @@ var PtySession = class {
 	inFlight = 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）。 */
@@ -2160,10 +2186,11 @@ var PtySession = class {
 	get detachedCommandId() {
 		return this.detachedJob?.commandId ?? null;
 	}
-	/** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId，账本如实记录两者）。 */
+	/** 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() {
@@ -2197,28 +2224,55 @@ var PtySession = class {
 	async warm() {
 		await this.start();
 	}
-	/** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。P4/P5（2026-10-19）：超时不再自动
-	* 打断——handoff 成 running job（byte-cursor 轮询 + 显式 interrupt，P8 机制原样保留在
-	* job.interrupt）；background 选项让 dispatch 立即回执。占用者是 detached job 时新命令
-	* 拒绝（Q6：诚实回状态优先于排队），纯同步并发 FIFO 语义不变。 */
+	/** 同一会话命令占位制（2026-10-25 interactive-stdin 轮）：dispatch 入口**同步**建立
+	* 命令占位（activeCommand + inFlight + 账本条目）——上一条命令仍在运行（同步等待 /
+	* 等输入 / detached job）时新 cmd 立即 E_SESSION_BUSY；原「纯同步并发排 FIFO」语义
+	* 废除（排队会让等输入的命令与补输入动作互相卡死，也给 busy 留下绕行窗口）。
+	* P4/P5：超时不杀命令而是 handoff 成 running job；background 立即回执；P8 显式
+	* interrupt 保留在 job.interrupt；死亡/冷态先重启（reconnect 语义不变）。 */
 	dispatch(cmd, dOpts) {
+		if (this.state === "disposed") return Promise.reject(/* @__PURE__ */ new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`));
+		if (this.activeCommand !== null) {
+			const handle = this.activeCommand.jobId ?? this.activeCommand.commandId;
+			return Promise.reject(/* @__PURE__ */ new Error(`[E_SESSION_BUSY] remote: pty session '${this.opts.id}' still runs a command (${this.activeCommand.commandId}) — 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 '${this.opts.id}' was disposed before dispatch`);
-			if (this.detachedJob !== null) throw new Error(`[E_SESSION_BUSY] remote: pty session '${this.opts.id}' still runs a detached command (${this.detachedJob.commandId}) — poll job_output ${this.detachedJob.commandId}, cancel with job_kill ${this.detachedJob.commandId}, or address other work to another session / oneshot`);
-			const commandId = dOpts.commandId;
-			const entry = {
-				commandId,
-				summary: summaryOf(cmd),
-				exit: null,
-				durationMs: 0,
-				running: true
+			/** 占位撤销：命令从未真正启动（建连失败 / 建连中被 dispose）——释放 busy 与计数，
+			* 撤掉账本条目（与旧时序等价：条目原本在 start 成功之后才建立）。 */
+			const abandon = () => {
+				this.activeCommand = null;
+				this.inFlight--;
+				const index = this.ledger.indexOf(entry);
+				if (index >= 0) this.ledger.splice(index, 1);
 			};
-			this.ledger.push(entry);
-			if (this.ledger.length > LEDGER_MAX) this.ledger.shift();
-			this.inFlight++;
+			if (this.state !== "ready") try {
+				await this.start();
+			} catch (error) {
+				abandon();
+				throw error;
+			}
+			if (this.state === "disposed") {
+				abandon();
+				throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.id}' was disposed before dispatch`);
+			}
 			return await new Promise((resolve$1) => {
 				const nonce = genNonce();
 				const ring = new Utf16TailRing(OUTPUT_HARD_CAP);
@@ -2227,6 +2281,7 @@ var PtySession = class {
 				let jobSettled = false;
 				let interruptTimer;
 				let killTimer;
+				let markerTimer;
 				let jobDone = null;
 				let envNext;
 				const detach = () => {
@@ -2260,9 +2315,11 @@ var PtySession = class {
 				const cleanup = () => {
 					this.onChunk = null;
 					this.detachedJob = null;
+					this.activeCommand = null;
 					this.deathWaiters = this.deathWaiters.filter((w) => w !== deathWaiter);
 					if (interruptTimer !== void 0) clearTimeout(interruptTimer);
 					if (killTimer !== void 0) clearTimeout(killTimer);
+					if (markerTimer !== void 0) clearTimeout(markerTimer);
 				};
 				const settle = (r) => {
 					if (jobSettled) return;
@@ -2317,7 +2374,9 @@ var PtySession = class {
 				const twoStage = () => {
 					interrupted = true;
 					this.write("");
-					this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					markerTimer = setTimeout(() => {
+						this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					}, MARKER_SETTLE_MS);
 					killTimer = setTimeout(() => {
 						this.killTree();
 						this.markDead();
@@ -2340,9 +2399,33 @@ var PtySession = class {
 				interruptTimer = setTimeout(() => detach(), dOpts.timeoutSec === void 0 ? 12e4 : dOpts.timeoutSec * 1e3);
 			});
 		};
-		const run = this.queue.then(attempt, attempt);
-		this.queue = run.then(() => void 0, () => void 0);
-		return run;
+		return attempt();
+	}
+	/** §3.1（2026-10-25）interactive-stdin：向当前运行中的命令追加 stdin——只写既有通道
+	* 与身份，不新建命令、账本条目或输出游标；不重连、不重放（dead/disposed 明确拒绝）。
+	* 校验与写入全同步：多次 input 按调用顺序整段写入不交错；写入失败如实抛错（私有
+	* write() 的静默忽略不适用于回执语义）。stdin:"" 是零字节写入，不是 EOF。 */
+	input(options) {
+		const fail = (code, hint) => Promise.reject(/* @__PURE__ */ new Error(`${code} remote: ${hint}`));
+		if (this.state === "disposed") return fail("[E_SESSION_DISPOSED]", `pty session '${displayKey(this.opts.key)}' was disposed — input never reaches a disposed session`);
+		if (this.state === "dead") return fail("[E_SESSION_NOT_RUNNING]", `pty session '${displayKey(this.opts.key)}' died — input never reconnects or replays; start a new command (exec reconnects a fresh shell) and re-send only what is still needed`);
+		if (this.state === "starting") return fail("[E_SESSION_NOT_READY]", `pty session '${displayKey(this.opts.key)}' is still initializing — wait for the exec receipt, then input`);
+		const active = this.activeCommand;
+		if (active === null) return fail("[E_SESSION_NOT_RUNNING]", `pty session '${displayKey(this.opts.key)}' has no running command (state ${this.state}) — input writes into a command started by exec; it is never an implicit shell command`);
+		if (options.commandId !== void 0 && options.commandId !== active.commandId) return fail("[E_COMMAND_MISMATCH]", `commandId ${JSON.stringify(options.commandId)} does not match the running command ${active.commandId} — input aimed at an earlier prompt is never written to the next command`);
+		const stdin = this.proc?.stdin;
+		if (stdin?.writable !== true) return fail("[E_SESSION_WRITE_FAILED]", `pty session '${displayKey(this.opts.key)}' has no writable stdin channel (state ${this.state}) — follow the running command via job_output for its settled result`);
+		try {
+			stdin.write(options.stdin);
+		} 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() {
@@ -2351,6 +2434,7 @@ var PtySession = class {
 		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);
@@ -2361,7 +2445,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;
 	}
@@ -2402,6 +2486,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();
@@ -2669,7 +2756,15 @@ function parseTargetForm(target) {
 			form: "hub-pty",
 			machine: segs[0]
 		};
-		throw new TargetFormatError(`[E_TARGET_FORMAT] remote: ${JSON.stringify(target)} — hub PTY takes no label (hub lane has no session id / parallelism this round)`);
+		if (segs.length === 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;
@@ -3092,6 +3187,16 @@ function renderRoster(scan, entries, sessions, hubTargets) {
 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 会话池。 */
@@ -3155,32 +3260,12 @@ var RemoteDriver = class {
 	}
 	async execute(params, form, callCtx) {
 		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
-		const cap = this.opts.maxOutputChars ?? 3e4;
 		const sessionKey = callCtx.sessionKey ?? "no-session";
 		const hasCmd = params.cmd !== void 0 && params.cmd.length > 0;
 		params.spawn !== void 0 && params.spawn.length;
-		if (form.form === "hub" || form.form === "hub-pty") {
+		if (form.form === "hub") {
 			const hub = this.requireHub();
 			this.hubProviders.add(hub);
-			if (form.form === "hub-pty") {
-				if (!hasCmd) throw new Error("[E_PARAMS] remote: hub PTY takes cmd");
-				const result$1 = await hub.pty(form.machine, params.cmd, this.hubOwner, {
-					stdin: params.stdin,
-					timeout: timeoutSec
-				});
-				const out$1 = tailWindow(result$1.stdout, cap, result$1.outputStats?.stdout);
-				return {
-					...result$1,
-					target: `hub:${form.machine}`,
-					connection: `hub:${form.machine}`,
-					stdout: `[hub:${form.machine} pty — no session id, no parallel, no background]\n${out$1.text}`,
-					...out$1.stats ? { outputStats: {
-						...result$1.outputStats,
-						stdout: out$1.stats
-					} } : {},
-					...out$1.truncated === void 0 ? {} : { truncated: out$1.truncated }
-				};
-			}
 			const process$1 = this.own(await hub.start(form.machine, {
 				...params,
 				target: `hub:${form.machine}`,
@@ -3190,8 +3275,8 @@ var RemoteDriver = class {
 			if (this.disposed) process$1.cancel("owner disposed");
 			const result = await process$1.done;
 			const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
-			const out = tailWindow(stdout.text, cap, stdout.stats);
-			const err = tailWindow(stderr.text, cap, stderr.stats);
+			const out = disclose(stdout.text, stdout.stats);
+			const err = disclose(stderr.text, stderr.stats);
 			return {
 				...result,
 				mode: "oneshot",
@@ -3199,6 +3284,7 @@ var RemoteDriver = class {
 				connection: `hub:${form.machine}`,
 				cwd: null,
 				reconnected: false,
+				runner: HUB_RUNNER,
 				stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out.text,
 				stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
 				...out.stats ? { outputStats: {
@@ -3215,7 +3301,7 @@ var RemoteDriver = class {
 				await session.warm();
 				return this.warmReceipt(session);
 			}
-			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
 		}
 		if (params.ssh !== void 0) {
 			const label = form.form === "direct" || form.form === "bare" ? form.name : void 0;
@@ -3236,28 +3322,28 @@ var RemoteDriver = class {
 				kind: "ssh",
 				host: normalizeSshConnection(params.ssh).host,
 				connection: normalizeSshConnection(params.ssh)
-			}, `ssh:${name$1}`, params, timeoutSec, cap);
+			}, `ssh:${name$1}`, params, timeoutSec);
 		}
 		if (form.form === "pty-selector" && form.idOrLabel === void 0) throw new Error("[E_PARAMS] remote: \"pty\" alone selects nothing — append an id/label (pty:pty-1a2b, pty:build) or pass spawn to create one");
 		if (form.form === "pty-selector") {
 			const session = this.resolvePty(form.idOrLabel, sessionKey);
 			if (!hasCmd) return this.cardReceipt(session);
-			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
 		}
 		if (form.form === "direct") {
 			const plan$1 = form.transport === "ssh" ? this.sshPlanFor(form.name, sessionKey) : resolveTarget(`${form.transport}:${form.name}`);
-			return await this.oneshot(plan$1, `${form.transport}:${form.name}`, params, timeoutSec, cap);
+			return await this.oneshot(plan$1, `${form.transport}:${form.name}`, params, timeoutSec);
 		}
 		if (form.form !== "bare") throw new Error("[E_INTERNAL] remote: unreachable target form after routing");
 		const entry = await this.resolvePoolEntry(form.name, sessionKey);
 		if (entry.kind === "pty") {
 			const session = this.resolvePty(form.name, sessionKey);
 			if (!hasCmd) return this.cardReceipt(session);
-			return await this.dispatchPty(session, params, callCtx, timeoutSec, cap);
+			return await this.dispatchPty(session, params, callCtx, timeoutSec);
 		}
-		if (entry.kind === "hub") return await this.hubOneshot(entry.machine, `hub:${entry.machine}`, params, timeoutSec, cap);
+		if (entry.kind === "hub") return await this.hubOneshot(entry.machine, `hub:${entry.machine}`, params, timeoutSec);
 		const plan = this.planOf(entry);
-		return await this.oneshot(plan, form.name, params, timeoutSec, cap);
+		return await this.oneshot(plan, form.name, params, timeoutSec);
 	}
 	/** Native-first copy routing (spec: remote-native-shortcut) — unchanged by the workbench round. */
 	copy(request, signal, callCtx = {}) {
@@ -3701,6 +3787,18 @@ var RemoteDriver = class {
 				...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) };
+		}
 	}
 	/** background PTY lane：会话先占位（不拨号）再进官方 jobs registry——首回执必须能寻址；
 	* registry 拒绝时把新建的会话拆掉（复用形的会话绝不拆）。返回 undefined = 走普通 oneshot job。 */
@@ -3788,15 +3886,50 @@ var RemoteDriver = class {
 			this.pool.get(key)?.attachJob(commandId, jobId);
 		}
 	}
-	async dispatchPty(session, params, callCtx, timeoutSec, cap) {
+	/** §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) {
+		const hubConn = session.identity.connection;
+		if (hubConn.startsWith("hub:")) {
+			const hub = this.requireHub();
+			this.hubProviders.add(hub);
+			hub.ptyEndpoint(hubConn.slice(4));
+		}
 		const commandId = callCtx.commandId ?? genCommandId();
 		const r = await session.dispatch(params.cmd, {
 			stdin: params.stdin,
 			timeoutSec,
 			commandId,
-			...callCtx.ptyBackground === true ? { background: true } : {}
+			...callCtx.ptyBackground === true ? {
+				background: true,
+				jobId: commandId
+			} : {}
 		});
-		const out = tailWindow(r.output, cap, r.outputStats?.stdout);
+		const out = disclose(r.output, r.outputStats?.stdout);
 		const id = session.identity;
 		return {
 			mode: "pty",
@@ -3864,7 +3997,7 @@ var RemoteDriver = class {
 			...this.ptyTtl(session.key)
 		};
 	}
-	async oneshot(plan, display, params, timeoutSec, cap) {
+	async oneshot(plan, display, params, timeoutSec) {
 		this.assertOpen();
 		const process$1 = this.own(await this.nativeProcess(plan, params, timeoutSec));
 		if (this.disposed) process$1.cancel("owner disposed");
@@ -3879,8 +4012,8 @@ var RemoteDriver = class {
 				stderr: stderr.stats
 			}
 		};
-		const out = tailWindow(r.stdout, cap, r.outputStats?.stdout);
-		const err = r.stderr.length > 0 ? tailWindow(r.stderr, cap, r.outputStats?.stderr) : void 0;
+		const out = disclose(r.stdout, r.outputStats?.stdout);
+		const err = r.stderr.length > 0 ? disclose(r.stderr, r.outputStats?.stderr) : void 0;
 		return {
 			mode: "oneshot",
 			target: display,
@@ -3899,13 +4032,13 @@ var RemoteDriver = class {
 			...this.runnerOf.get(process$1) === void 0 ? {} : { runner: this.runnerOf.get(process$1) }
 		};
 	}
-	async hubOneshot(machine, display, params, timeoutSec, cap) {
+	async hubOneshot(machine, display, params, timeoutSec) {
 		const process$1 = this.own(await this.hubOneshotProcess(machine, params));
 		if (this.disposed) process$1.cancel("owner disposed");
 		const result = await process$1.done;
 		const stdout = process$1.read("stdout", 0), stderr = process$1.read("stderr", 0);
-		const out = tailWindow(stdout.text, cap, stdout.stats);
-		const err = tailWindow(stderr.text, cap, stderr.stats);
+		const out = disclose(stdout.text, stdout.stats);
+		const err = disclose(stderr.text, stderr.stats);
 		return {
 			...result,
 			mode: "oneshot",
@@ -3913,6 +4046,7 @@ var RemoteDriver = class {
 			connection: display,
 			cwd: null,
 			reconnected: false,
+			runner: HUB_RUNNER,
 			stdout: (!stdout.stats && stdout.lossy ? "[truncated: peer returned only a tail; exact total/retained/dropped unavailable]\n" : "") + out.text,
 			stderr: [err.text, stderr.diagnostic].filter(Boolean).join("\n"),
 			...out.stats ? { outputStats: {
@@ -4070,16 +4204,20 @@ const ptyOutputSources = (holder) => [{
 		lossy: false
 	}
 }];
-const ptyOutcome = (aborted, result) => ({
-	status: aborted ? "killed" : result.exit === null ? "failed" : "completed",
-	detail: aborted ? `interrupted: ${result.exit === null ? "session died" : `exit ${result.exit}`}` : result.exit === null ? "session died" : `exit code: ${result.exit}`
-});
+/** 0.3.2-d CF：timedOut=true 且 aborted=false = 会话侧主动收束（close force / 行回收走的
+* dispose→interrupt 两段路）——同为 killed；exit 到手用 exit，只剩会话死亡时写 session closed。 */
+const ptyOutcome = (aborted, result) => {
+	const interrupted = aborted || result.timedOut === true;
+	return {
+		status: interrupted ? "killed" : result.exit === null ? "failed" : "completed",
+		detail: interrupted ? `interrupted: ${result.exit === null ? aborted ? "session died" : "session closed" : `exit ${result.exit}`}` : result.exit === null ? "session died" : `exit code: ${result.exit}`
+	};
+};
 /** No preparation or discovery before the official registry's admission. */
 function startRemoteJob(registry, input, exec, driver) {
 	if (!exec.agent) throw new Error("remote: background jobs require a live Agent owner");
 	const form = parseTargetForm(input.target);
 	if (form.form === "pty-selector" || form.form === "create-pty" || form.form === "hub-pty" || input.spawn !== void 0 || input.mode === "pty") {
-		if (form.form === "hub-pty") throw new Error("remote: hub-machine PTY has no background lane; use a direct ssh/docker/incus target or a pty session");
 		const holder = {};
 		return registry.start({
 			kind: "remote",
@@ -4205,116 +4343,157 @@ function adoptRunningPtyJob(registry, exec, label, job) {
 
 //#endregion
 //#region src/remote/tool.ts
-const NO_SESSION_KEY = "remote:no-session";
+const NO_SESSION_KEY$1 = "remote:no-session";
 /**
-* The model-visible surface of the `remote` tool (workbench round, plan
-* 2026-10-19-pty-workbench). ONE template literal — no backticks, no "${".
+* The model-visible surface of the `remote` tool (0.3.2-d user-ruled restructure:
+* Actions / Targets / PTY / Oneshot / Examples — the PTY block is the user's verbatim
+* final draft; Examples receipts match renderValue byte-for-byte).
+* ONE template literal — no backticks, no "${".
+*
+* 语义目标（surface 就是产品）：动作是唯一的派发维度；PTY 四词定位——stateful oneshot /
+* interact-able stdin / managed output / persistent env——回执形状与 oneshot 相同、只增状态，
+* 运行中的命令可分步观察后再补输（input 动作）；多步与交互任务默认进 PTY。
 */
-const REMOTE_TOOL_DESCRIPTION = `Remote execution and file transfer over ssh / docker / incus, plus stateful PTY workbenches. Pick the call shape:
-  {}                                   → roster (local scan; refreshes the name pool: ssh aliases, BYO identities, docker/incus containers, hub machines, live pty sessions)
-  {target}                             → status probe: machine reachability + its pty sessions, or a session card (connection, cwd, ledger of the last 20 commands) for pty:<id|label>
-  {target, cmd}                        → run cmd — oneshot (stateless bash -lc) on any machine target
-  {target, scriptPath:"/abs"}         → LOCAL script over stdin to a fixed bash -s (oneshot only; no cmd/stdin/spawn mix)
-  {target:"ssh:dev4:pty[:label]", cmd?}    → create a PTY session on that machine and run cmd in it; no cmd = warm creation returning the id. Tab semantics: every creation call opens a NEW session — parallel is first-class (max 10 per Agent, ssh:dev4 and docker:corti alike).
-  {target:"pty:<id|label>", cmd}           → run cmd in a live session (cwd/env survive; the receipt carries session, connection, commandId, cwd, env delta, idle-left)
-  {spawn, target?:"pty[:<label>]"|"<label>"|"", cmd?}  → create a BYO pty from a spawn command (e.g. docker exec -it img bash; nested hops are dumb pipes). spawn present IS the BYO entry point; no target = auto id.
-  {ssh:{...}, target?:"ssh[:<label>]"|"<label>"|"", cmd?}  → register a BYO ssh identity (ssh present IS the entry point); the label then works everywhere ssh: aliases do (roster marks it "built on"); ssh:<label>:pty opens a session on it. key is an existing origin file, never inline material; nothing is persisted; a new Agent registers again.
-  {action:"close", target:"pty:<id|label>", force?}  → close a session. Idempotent (unknown id → closed:false). Default rejects while a job is running and names it (job_kill it first, or wait); force:true closes the tab and kills the group in one step.
-  {action:"copy"|"rsync", src, dst, argv?}  → file transfer (see the action/src/dst fields)
-Bare names address ONE unified pool (machines + identities + sessions — roster lists it; a machine losing its bare name to an earlier claim is shown prefixed docker-foo / incus-foo). Prefixes ssh: / docker: / incus: / hub: force a channel. Creation always claims a fresh name: a taken label answers [E_LABEL_IN_USE] — address it without creation params, or pick another (specs are never compared). PTY sessions idle out after 15 min (running commands exempt; reads do not reset the clock).
+const REMOTE_TOOL_DESCRIPTION = `Remote shell over ssh / docker / incus (Hub when configured): stateless oneshots + persistent interactive PTY sessions. Default to PTY for multi-step or interactive work; oneshot for isolated commands.
+
+Actions (action is the only dispatch dimension; unknown fields are rejected):
+- exec {target, cmd | scriptPath, stdin?, timeout?, run_in_background?}: run a command. Machine target → oneshot; pty:<id|label> → run inside that live session; <machine>:pty[:label] → create a NEW session and run there.
+- add {ssh:{...} | spawn:"<cmd>", target?}: register a BYO endpoint (identity or interactive-shell command); no command runs. Returns the addressable label; a taken label answers [E_LABEL_IN_USE] — address existing names directly, never add again.
+- status {}: roster — the one unified pool (machines, identities, live PTY sessions).
+- status {target}: machine probe, or a session card (connection, cwd, ledger of the last 20 commands).
+- input {target:"pty:<id|label>", stdin, commandId?}: write stdin into the command currently running in that session — passwords, OTP, tokens, menu choices, REPL lines. Never creates a session, never dials.
+- close {target, force?}: close a PTY session; a running command refuses it (job_kill first) unless force:true kills it in the same step.
+
+Targets:
+- ssh:<name> / docker:<name> / incus:<name> / bare pool name → stateless oneshot.
+- <machine>:pty[:label] → NEW PTY every call — creation is a target suffix, not a different tool.
+- pty:<id|label> (or its bare label) → REUSE the live session.
+After creation, reuse the returned session; repeating :pty opens another. Prefixes force the channel; bare names resolve through the roster.
+
+PTY:
+- stateful oneshot, interact-able stdin, managed output, persistent env
+- timeout (default 120s) → command keeps running; returns job handle.
+- run_in_background → same job lane. jobId = commandId.
+- Read: job_output(jobId). Cancel: job_kill; try Ctrl-C first.
+- Busy session: input / poll / cancel / use another session.
+- exec.stdin = startup input; input = subsequent input.
+- input is verbatim: "\\n" submits; "\\u0003" Ctrl-C; "\\u0004" Ctrl-D; "" writes nothing. Ctrl-D follows terminal EOF rules.
+- commandId, if supplied, must match running command.
+- Input receipt confirms write only; read result via SAME job.
+- Output returns in full up to retention (4M chars per stream; Hub oneshot 4MiB bytes) — beyond it the retained tail plus outputStats. Redirect bulk output to files.
+- Idle expiry: 15 min; running commands exempt.
+
+Oneshot:
+- stdout/stderr separate, exit code verbatim; no retained shell state. stdin is startup-only: there is no input after start — a prompt on a oneshot means cancel (job_kill) and switch to PTY. Heredocs and input redirection remain valid bulk-input alternatives.
+- Supervision prefers a pinned superd-run helper cached on the endpoint (~/.cache/superd/run), falls back to a POSIX shim — the receipt field "runner" says which ran. Either way children are reaped on completion and the whole group is killed on timeout/cancel. The endpoint needs bash only — no Python.
+- scriptPath (oneshot only): a LOCAL absolute script read before any dialing, sent literally over stdin to a fixed bash -s — the file carrier for multi-line scripts; pairs with neither cmd nor stdin.
+
+Examples
+
+Manage the persistent PTY session. One-shot style output, but stable: every command returns synchronously with exit, cwd, and an env delta.
+
+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.
+
+remote { "action": "add", "spawn": "ssh -t pc ssh -t dev4", "target": "pty:dev4via" }
 
-oneshot: stdout/stderr separate, exit code verbatim. Supervision prefers a pinned superd-run helper cached on the endpoint (~/.cache/superd/run; first call uploads it over the same exec lane) and falls back to a POSIX wrapper everywhere else — the receipt field "runner" says which ran. Helper or wrapper, backgrounded children are reaped on completion and the whole group is killed on timeout/cancel; the endpoint needs bash only (no Python).
+[session created — address it as pty:pty-irsq]
+[pty:pty-irsq (dev4via) (byo-pty) · conn BYOP · idle-left ~15m · exit null · 0.0s]
 
-PTY is the stateful superset of oneshot: every command returns synchronously with exit + cwd + an env delta (NAMES only — added/changed/removed; values never leave the endpoint; fetch a value yourself if you need it). A command that outlives its timeout is NOT killed — it hands off as a running job: poll job_output <commandId>, cancel with job_kill (Ctrl-C first; the session survives). run_in_background uses the same lane and its jobId IS the commandId. A busy session rejects new commands ([E_SESSION_BUSY] names the running id and the ways out: job_output / job_kill / another session or oneshot).
+remote { "action": "exec", "target": "pty:dev4via", "cmd": "hostname && sudo -n ss -tlnp | awk 'NR==1 || /LISTEN/' | head -5" }
 
-Output: pty tails at ~30k chars ("[truncated: …]" header) — redirect bulk output to a file. Hard retention 4,000,000 UTF-16 units per stream (Hub 4MiB bytes); outputStats reports the rest; restart cannot recover discarded output. stdin feeds the command (pty: REPL-style right after the command line — only helps commands that read stdin there). timeout (seconds, default 120): oneshot interrupts then kills the whole group; pty hands off. Native transport errors pass through verbatim — self-correct from them.`;
+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) {
-	if (args.action === "copy" || args.action === "rsync") {
-		if (!args.src || !args.dst) throw new Error(`${args.action} requires src and dst absolute endpoints`);
-		if ([
-			args.cmd,
-			args.scriptPath,
-			args.stdin,
-			args.spawn,
-			args.ssh,
-			args.target,
-			args.timeout,
-			args.run_in_background,
-			args.force
-		].some((value) => value !== void 0)) throw new Error(`${args.action} cannot be combined with execution/PTY/job arguments`);
-		const KNOWN_PARAMS = new Set([
-			"action",
-			"force",
-			"src",
-			"dst",
-			"argv",
-			"pullArgv",
-			"pushArgv",
-			"verify",
-			"mkdir",
-			"run_in_background",
-			"target",
-			"ssh",
-			"spawn",
-			"cmd",
-			"scriptPath",
-			"stdin",
-			"timeout"
-		]);
-		for (const key of Object.keys(args)) if (!KNOWN_PARAMS.has(key)) throw new Error(`remote: unknown parameter "${key}" — this surface has no legacy aliases; pass native CLI options through argv instead`);
-		if (args.action === "rsync") {
-			if (args.pullArgv !== void 0 || args.pushArgv !== void 0) throw new Error("rsync takes argv only; pullArgv/pushArgv are copy-only fields");
-			if ([args.verify, args.mkdir].some((value) => value !== void 0)) throw new Error("rsync cannot be combined with copy verify/mkdir options; the Hub/local staged lane is copy-only");
-			const start = Date.now();
-			const receipt$1 = await ENV.driver.rsync({
-				src: args.src,
-				dst: args.dst,
-				...args.argv === void 0 ? {} : { argv: args.argv }
-			}, exec.signal, { sessionKey: ENV.getSessionKey(exec) });
-			if (receipt$1.ok === false || receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
-			const rsyncDuration = Date.now() - start;
-			return {
-				kind: "rsync",
-				text: formatTransferLine("rsync", receipt$1, rsyncDuration),
-				receipt: receipt$1,
-				exit: receipt$1.exit,
-				durationMs: rsyncDuration
-			};
-		}
-		const copyStart = Date.now();
-		const receipt = await ENV.driver.copy({
-			src: args.src,
-			dst: args.dst,
-			...args.verify === void 0 ? {} : { verify: args.verify },
-			...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
-			...args.argv === void 0 ? {} : { argv: args.argv },
-			...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
-			...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
-		}, exec.signal, { sessionKey: ENV.getSessionKey(exec) });
-		const asReceipt = receipt;
-		const exits = asReceipt.exits ?? [];
-		if (asReceipt.ok === false || exits.some((code) => code !== 0)) throw new Error(JSON.stringify(receipt));
-		const copyDuration = Date.now() - copyStart;
+	const action = args.action;
+	if (action === void 0) throw new Error("[E_PARAMS] remote: action is required — \"exec\" (run a command), \"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: "copy",
-			text: formatTransferLine("copy", receipt, copyDuration),
-			receipt,
-			exit: exits.length > 0 ? 0 : null,
-			durationMs: copyDuration
+			kind: "status",
+			text: await ENV.driver.status(args.target, { sessionKey }),
+			exit: null,
+			durationMs: 0
 		};
 	}
-	if (args.action === "close") {
-		if (typeof args.target !== "string" || args.target.length === 0) throw new Error("close requires target pty:<id|label>");
-		if ([
-			args.cmd,
-			args.scriptPath,
-			args.stdin,
-			args.spawn,
-			args.ssh,
-			args.timeout,
-			args.run_in_background
-		].some((value) => value !== void 0)) throw new Error("[E_PARAMS] close cannot be combined with execution/PTY/job arguments");
-		const r$1 = ENV.driver.closePty(args.target.startsWith("pty:") ? args.target.slice(4) : args.target, ENV.getSessionKey(exec), args.force === true);
+	if (action === "close") {
+		if (!hasTarget) throw new Error("[E_PARAMS] close requires target 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"}`,
@@ -4326,42 +4505,71 @@ async function remoteExecute(ENV, args, exec) {
 			killed: r$1.killed
 		};
 	}
-	if ([
-		args.src,
-		args.dst,
-		args.argv,
-		args.pullArgv,
-		args.pushArgv,
-		args.verify,
-		args.mkdir,
-		args.force
-	].some((value) => value !== void 0)) throw new Error("file/force fields require an action (copy / rsync / close)");
-	const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
-	const hasTarget = typeof args.target === "string" && args.target.length > 0;
-	const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
-	if (args.spawn !== void 0 && !hasSpawn) throw new Error("[E_PARAMS] remote: spawn must be a non-empty command string");
-	if (args.scriptPath !== void 0 && (hasSpawn || /^pty:/.test(args.target ?? "") || /:pty/.test(args.target ?? ""))) throw new Error("[E_SCRIPT_PARAMS] remote: scriptPath is oneshot-only — PTY lanes take cmd");
+	if (action === "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) {
-		if (!hasCmd && args.scriptPath === void 0) throw new Error("remote: background requires cmd or scriptPath");
 		const jobs = exec.agent?.ctx.get("jobs");
 		if (!jobs) throw new Error("remote: background requires the official DSH jobs service and job_output/job_kill controller; foreground execution remains available");
 		const lane = await ENV.driver.preparePtyLane({
 			target: args.target,
-			spawn: args.spawn,
 			cmd: args.cmd,
 			scriptPath: args.scriptPath,
-			ssh: args.ssh,
 			stdin: args.stdin,
 			timeout: args.timeout
-		}, { sessionKey: ENV.getSessionKey(exec) });
+		}, { sessionKey });
 		let jobId;
 		try {
 			jobId = startRemoteJob(jobs, lane !== void 0 ? lane.input : {
 				target: args.target,
-				spawn: args.spawn,
 				cmd: args.cmd,
 				scriptPath: args.scriptPath,
-				ssh: args.ssh,
 				stdin: args.stdin,
 				timeout: args.timeout
 			}, exec, ENV.driver);
@@ -4377,44 +4585,20 @@ async function remoteExecute(ENV, args, exec) {
 			durationMs: 0,
 			text: `Started ${jobId}${where}. Use job_output to read and job_kill to cancel; completion is reported by the host.`,
 			...lane !== void 0 ? {
+				commandId: jobId,
 				session: lane.session,
 				connection: lane.connection,
 				...lane.label !== void 0 ? { label: lane.label } : {}
 			} : {}
 		};
 	}
-	if (!hasCmd && args.scriptPath === void 0) {
-		if (args.stdin !== void 0) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd — status probes take no input");
-		const t = args.target ?? "";
-		if (hasSpawn || args.ssh !== void 0 || /^pty:/.test(t) || /:pty(:|$)/.test(t) && !t.startsWith("hub:")) return workbenchValue(await ENV.driver.call({
-			target: args.target,
-			spawn: args.spawn,
-			ssh: args.ssh,
-			cmd: "",
-			stdin: void 0
-		}, { sessionKey: ENV.getSessionKey(exec) }));
-		if (!hasTarget) return {
-			kind: "roster",
-			text: await ENV.driver.roster({ sessionKey: ENV.getSessionKey(exec) }),
-			exit: null,
-			durationMs: 0
-		};
-		return {
-			kind: "status",
-			text: await ENV.driver.status(args.target, { sessionKey: ENV.getSessionKey(exec) }),
-			exit: null,
-			durationMs: 0
-		};
-	}
 	const r = await ENV.driver.call({
 		target: args.target,
-		spawn: args.spawn,
-		ssh: args.ssh,
 		cmd: args.cmd,
 		scriptPath: args.scriptPath,
 		stdin: args.stdin,
 		timeout: args.timeout
-	}, { sessionKey: ENV.getSessionKey(exec) });
+	}, { sessionKey });
 	const v = workbenchValue(r);
 	if (r.running === true && r.ptyJob !== void 0) {
 		const jobs = exec.agent?.ctx.get("jobs");
@@ -4422,7 +4606,7 @@ async function remoteExecute(ENV, args, exec) {
 			const jobId = adoptRunningPtyJob(jobs, exec, `${r.target}: ${args.cmd}`, r.ptyJob);
 			v.jobId = jobId;
 			v.running = true;
-			if (r.commandId !== void 0 && jobId !== r.commandId) ENV.driver.attachPtyJob(r.commandId, jobId, ENV.getSessionKey(exec));
+			if (r.commandId !== void 0 && jobId !== r.commandId) ENV.driver.attachPtyJob(r.commandId, jobId, sessionKey);
 		} else {
 			r.ptyJob.interrupt();
 			v.notice = "The command outlived its synchronous wait and no jobs service is available to poll it, so it was interrupted. Use run_in_background:true for long commands.";
@@ -4431,7 +4615,7 @@ async function remoteExecute(ENV, args, exec) {
 	return v;
 }
 function createRemoteTool(driver, opts = {}) {
-	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY$1);
 	const tool = defineTool({
 		name: "remote",
 		description: REMOTE_TOOL_DESCRIPTION,
@@ -4439,58 +4623,42 @@ function createRemoteTool(driver, opts = {}) {
 			action: {
 				type: "string",
 				enum: [
-					"copy",
-					"rsync",
-					"close"
+					"exec",
+					"add",
+					"status",
+					"close",
+					"input"
 				],
-				description: "Optional action; omit for execution/status/roster. close takes target + optional force."
+				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."
 			},
-			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."
-			},
-			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"
+				description: "exec: one raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Required unless scriptPath is given."
 			},
-			argv: {
-				type: "array",
-				items: { type: "string" },
-				description: "Ordered native CLI options and values for one-command routes (e.g. rsync [\"-a\",\"--partial\",\"--dry-run\"], scp [\"-p\",\"-r\"], docker cp [\"-a\"], incus file push/pull). One element = one argv token, appended verbatim before src/dst; no shell parsing, no whitelist, no forced defaults — unknown options fail in the native CLI itself. rsync only (SSH endpoints): explicit -e/--rsh overrides the tool's SSH wiring. docker cp: pass -L to follow symlinks (a symlink source like /etc/os-release fails without it). Two-segment cross-endpoint copy uses pullArgv/pushArgv instead."
-			},
-			pullArgv: {
-				type: "array",
-				items: { type: "string" },
-				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
-			},
-			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."
+			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. 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."
+			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, 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."
+			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 AND pty: return a native jobId immediately, read with job_output, cancel with job_kill; output is available while running. On pty lanes the jobId IS the commandId — it tracks the running command inside a persistent session; job_kill sends Ctrl-C and the session survives. Hub-machine PTY has no background lane. Requires the official jobs service/controller."
-			},
-			target: {
-				type: "string",
-				description: "Single entry point. Machine targets: bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>. PTY: append :pty to create (ssh:dev4:pty, ssh:dev4:pty:build — label optional, every creation opens a new session) or address a live one with pty:<id|label>. BYO: pass spawn (pty) or ssh (identity) and the label lives in the same pool. Omit target → roster (or BYO auto-id when spawn/ssh present)."
+				description: "exec: 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: "BYO ssh registration — the field present IS the entry point. First call registers (no cmd = register only); later calls reuse the label with ssh omitted. No inline keys or arbitrary SSH options.",
+				description: "add: BYO ssh identity to register into the pool (no dialing). Later exec calls address the returned label. No inline keys or arbitrary SSH options; nothing is persisted — a new Agent registers again.",
 				additionalProperties: false,
 				properties: {
 					host: {
@@ -4518,23 +4686,11 @@ function createRemoteTool(driver, opts = {}) {
 			},
 			spawn: {
 				type: "string",
-				description: "BYO pty creation — the field present IS the entry point: the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). Pairs with target pty[:<label>] / a bare <label> / nothing (auto id). Nested hops are dumb pipes (only the innermost bash frames)."
-			},
-			cmd: {
-				type: "string",
-				description: "One raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Omit with target → status/card; omit everything → roster."
-			},
-			scriptPath: {
-				type: "string",
-				description: "LOCAL absolute script path. Read before any dialing, sent literally over stdin to fixed bash -s. Oneshot only (no PTY lanes); cannot combine with cmd, stdin or spawn. Hub inline cmd remains limited to 4096; script body is not argv."
+				description: "add: BYO PTY entry point — the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). Pairs with target pty[:<label>] / a bare <label> / nothing (auto id). Nested hops are dumb pipes (only the innermost bash frames)."
 			},
-			stdin: {
-				type: "string",
-				description: "Input fed to the command. oneshot: piped to stdin. pty: written right after the command line (REPL-style). Requires cmd."
-			},
-			timeout: {
-				type: "number",
-				description: "Per-command timeout in seconds (default 120). oneshot: interrupts then kills the whole group. pty: the command is NOT killed on timeout — it hands off to a running job you can poll (job_output) and cancel (job_kill = Ctrl-C first; the session survives an interrupt)."
+			force: {
+				type: "boolean",
+				description: "close only: default false — a session with a running job is refused (job_kill it first). true = kill the group and close in one step; the receipt lists what was killed."
 			}
 		},
 		output: {
@@ -4550,9 +4706,8 @@ function createRemoteTool(driver, opts = {}) {
 							"status",
 							"roster",
 							"job",
-							"copy",
-							"rsync",
-							"close"
+							"close",
+							"input"
 						]
 					},
 					text: {
@@ -4584,6 +4739,10 @@ function createRemoteTool(driver, opts = {}) {
 						type: "string",
 						description: "ledger key; equals the jobId whenever a job exists"
 					},
+					writtenBytes: {
+						type: "integer",
+						description: "input: UTF-8 bytes actually written; confirms the write, not the program response"
+					},
 					envDelta: {
 						type: "json",
 						description: "names only: {added,changed,removed}"
@@ -4592,7 +4751,7 @@ function createRemoteTool(driver, opts = {}) {
 					notice: { type: "string" },
 					runner: {
 						type: "string",
-						description: "oneshot supervision path: superd-run <ver> (<triple>) or posix-shim"
+						description: "oneshot supervision path: superd-run <ver> (<triple>), posix-shim, or hub-lease (peer hub server supervises natively)"
 					},
 					running: { type: "boolean" },
 					ttlSec: { type: "integer" },
@@ -4626,7 +4785,7 @@ function createRemoteTool(driver, opts = {}) {
 	const description = tool.description;
 	Object.defineProperty(tool, "description", {
 		enumerable: true,
-		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self). {} includes the Hub directory even when empty. Uses authenticated Hub HTTP oneshot / persistent WS PTY (hub:<m4>:pty selects the PTY lane); no SSH alias needed. Hub failures never fall back to SSH." : "")
+		get: () => description + (driver.hasHub() ? "\nHub transport available: hub:<m4> selects a paired remote machine (never self; the roster lists them). Hub failures never fall back to SSH.\n- hub:<m4> oneshot: the peer hub server is the runner itself — bash -lc in a detached group, TERM→2s→KILL cleanup; the receipt runner field says \"hub-lease\" (the superd-run helper is a dumb-pipe artifact, never uploaded over the Hub). 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;
 }
@@ -4657,26 +4816,6 @@ function workbenchValue(r) {
 	if (r.ttlSec !== void 0) v.ttlSec = r.ttlSec;
 	return v;
 }
-/** S8 (2026-10-17): copy/rsync render as one formatted line; the full receipt
-* stays in the receipt field — raw-JSON dumps are gone from text. */
-function formatTransferLine(action, receipt, durationMs) {
-	const r = receipt;
-	const parts = [];
-	if (r.ok === false) parts.push(`✗ ${r.reason ?? "failed"}`);
-	parts.push(`${action} ${r.src} → ${r.dst}`);
-	if (r.route !== void 0 && r.route !== "") parts.push(`route ${r.route}`);
-	if (r.exits !== void 0) parts.push(`exits [${r.exits.join(",")}]`);
-	else if (r.exit !== void 0) parts.push(`exit ${r.exit}`);
-	if (r.verification !== void 0) parts.push(`verification ${r.verification}`);
-	if (r.created === true) parts.push("created yes");
-	else if (r.created === false) parts.push("created pre-existing");
-	else if (r.created === "n-a") parts.push("created n-a");
-	if (r.cleanup !== void 0 && r.cleanup !== "none-required") parts.push(`cleanup ${r.cleanup}`);
-	if (typeof r.bytes === "number") parts.push(`${r.bytes} bytes / ${r.entries} entries`);
-	parts.push(`${(durationMs / 1e3).toFixed(1)}s`);
-	if (r.note !== void 0 && r.note.length > 0) parts.push(`(${r.note})`);
-	return parts.join(" · ");
-}
 function renderEnvDelta(d) {
 	const bits = [];
 	if (d.added.length > 0) bits.push(`+${d.added.join(",+")}`);
@@ -4685,7 +4824,7 @@ function renderEnvDelta(d) {
 	return bits.length > 0 ? bits.join(" ") : void 0;
 }
 function renderValue(v) {
-	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "copy" || v.kind === "rsync" || v.kind === "close") return v.text;
+	if (v.kind === "status" || v.kind === "roster" || v.kind === "job" || v.kind === "close" || v.kind === "input") return v.text;
 	const parts = [];
 	if (v.reconnected === true) parts.push(RECONNECT_NOTICE);
 	if (typeof v.notice === "string" && v.notice.length > 0) parts.push(v.notice);
@@ -4706,15 +4845,188 @@ function renderValue(v) {
 	markers.push(`${secs}s`);
 	if (v.running === true) markers.push(`still running — poll job_output${v.jobId !== void 0 ? ` ${v.jobId}` : ""}`);
 	if (v.truncated !== void 0) markers.push(`truncated, ${v.outputStatsUnavailable ? "returned peer tail" : "original"} ${v.truncated} ${v.outputStats?.stdout.unit === "bytes" ? "bytes" : "chars"}`);
-	if (v.outputStatsUnavailable) markers.push("peer output totals/retention unavailable; returned tail only");
+	if (v.outputStatsUnavailable) markers.push("peer output totals/retention unavailable");
 	parts.push(`[${markers.join(" · ")}]`);
 	if (v.runner === "posix-shim" && (v.exit !== null && v.exit !== 0 || v.timedOut === true)) parts.push("note: this oneshot ran through the POSIX fallback on this target; PTY lanes use an independent lane and may still work here");
 	if (v.stderr !== void 0 && v.stderr.length > 0) parts.push("[stderr]", v.stderr);
 	return parts.join("\n");
 }
 
+//#endregion
+//#region src/remote/transfer-tool.ts
+const NO_SESSION_KEY = "remote:no-session";
+/**
+* The model-visible surface of the `remote_transfer` tool (split out of
+* `remote`, 2026-10-25). ONE template literal — no backticks, no "${".
+*/
+const TRANSFER_TOOL_DESCRIPTION = `File transfer between any two supported endpoints. Every call declares its mode:
+  mode:"copy"   → tree copy. Native CLI per endpoint (scp for ssh, docker cp, incus file push/pull), a plain tree copy when both ends are local, and the Hub binary lane when a Hub machine is involved. Directories copy recursively; exit codes are authoritative.
+  mode:"rsync"  → rsync over SSH only: at least one endpoint remote SSH, the other local or SSH (both remote legs tunnel through this machine; identities never leave it). Hub and container endpoints are rejected — no silent copy fallback. Trailing slashes keep rsync semantics.
+
+Endpoints are "[target:]absolute path". No target = the machine running this Agent. Targets are the same unified pool remote uses: a bare pool name, ssh:<name>, docker:<name>, incus:<name>, hub:<m4>. Examples: "/srv/app", "ssh:dev4:/srv/app", "docker:corti:/var/lib/x", "hub:m4:/srv". A path is never guessed: both operands must be absolute.
+
+Native CLI options travel through argv verbatim — one element = one token, appended before src/dst, no shell parsing and no whitelist: rsync ["-a","--partial"], scp ["-p","-r"], docker cp ["-a","-L"], incus file push ["--recursive"]. Cross-endpoint copies that need two commands (SSH↔Docker, SSH↔Incus, Docker↔Incus) take pullArgv plus pushArgv instead of argv. rsync is a single SSH command, so it takes argv only; an explicit -e/--rsh overrides the wiring.
+
+Options: verify (copy only) — the Hub↔local staged lane computes independent SHA-256 digests by default and verify:false skips them; native CLI routes have no independent hash tier, so verify is rejected there (self-verify through a oneshot digest command). mkdir (copy only, default true) — one best-effort pre-hop creates the destination PARENT directory; the operand itself is never pre-created, so each CLI's own layout semantics stay byte-identical.
+
+Failures are loud: a non-zero native exit throws with the receipt instead of returning a normal-looking result. The receipt stays in the receipt field (route, exits, verification, bytes/entries, cleanup); text is one formatted line. For checksum-grade verification of a native route, run a digest command through remote oneshot or PTY instead of trusting the copy receipt.`;
+const KNOWN_PARAMS = new Set([
+	"mode",
+	"src",
+	"dst",
+	"argv",
+	"pullArgv",
+	"pushArgv",
+	"verify",
+	"mkdir"
+]);
+async function transferExecute(ENV, args, exec) {
+	for (const key of Object.keys(args)) if (!KNOWN_PARAMS.has(key)) throw new Error(`remote_transfer: unknown parameter "${key}" — this surface has no legacy aliases; pass native CLI options through argv instead`);
+	if (args.mode !== "copy" && args.mode !== "rsync") throw new Error(`[E_PARAMS] remote_transfer: mode is required — "copy" (tree copy through each endpoint's native CLI or the Hub lane) or "rsync" (SSH only)`);
+	if (typeof args.src !== "string" || args.src.length === 0 || typeof args.dst !== "string" || args.dst.length === 0) throw new Error(`[E_PARAMS] remote_transfer: ${args.mode} requires src and dst absolute endpoints`);
+	const sessionKey = ENV.getSessionKey(exec);
+	if (args.mode === "rsync") {
+		if (args.pullArgv !== void 0 || args.pushArgv !== void 0) throw new Error("remote_transfer: rsync takes argv only; pullArgv/pushArgv are copy-only fields");
+		if (args.verify !== void 0 || args.mkdir !== void 0) throw new Error("remote_transfer: rsync cannot be combined with copy verify/mkdir options; the Hub/local staged lane is copy-only");
+		const start$1 = Date.now();
+		const receipt$1 = await ENV.driver.rsync({
+			src: args.src,
+			dst: args.dst,
+			...args.argv === void 0 ? {} : { argv: args.argv }
+		}, exec.signal, { sessionKey });
+		if (receipt$1.ok === false || receipt$1.exit !== 0) throw new Error(JSON.stringify(receipt$1));
+		const durationMs$1 = Date.now() - start$1;
+		return {
+			kind: "rsync",
+			text: formatTransferLine("rsync", receipt$1, durationMs$1),
+			receipt: receipt$1,
+			exit: receipt$1.exit,
+			durationMs: durationMs$1
+		};
+	}
+	const start = Date.now();
+	const receipt = await ENV.driver.copy({
+		src: args.src,
+		dst: args.dst,
+		...args.verify === void 0 ? {} : { verify: args.verify },
+		...args.mkdir === void 0 ? {} : { mkdir: args.mkdir },
+		...args.argv === void 0 ? {} : { argv: args.argv },
+		...args.pullArgv === void 0 ? {} : { pullArgv: args.pullArgv },
+		...args.pushArgv === void 0 ? {} : { pushArgv: args.pushArgv }
+	}, exec.signal, { sessionKey });
+	const asReceipt = receipt;
+	const exits = asReceipt.exits ?? [];
+	if (asReceipt.ok === false || exits.some((code) => code !== 0)) throw new Error(JSON.stringify(receipt));
+	const durationMs = Date.now() - start;
+	return {
+		kind: "copy",
+		text: formatTransferLine("copy", receipt, durationMs),
+		receipt,
+		exit: exits.length > 0 ? 0 : null,
+		durationMs
+	};
+}
+function createRemoteTransferTool(driver, opts = {}) {
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	return defineTool({
+		name: "remote_transfer",
+		description: TRANSFER_TOOL_DESCRIPTION,
+		parameters: {
+			mode: {
+				type: "string",
+				enum: ["copy", "rsync"],
+				required: true,
+				description: "Required. copy = tree copy through each endpoint's native CLI, or the Hub binary lane; rsync = SSH only (argv only, no verify/mkdir)."
+			},
+			src: {
+				type: "string",
+				description: "Source [target:]absolute path. No target = the machine running this Agent."
+			},
+			dst: {
+				type: "string",
+				description: "Destination [target:]absolute path. No target = the machine running this Agent."
+			},
+			argv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Ordered native CLI options and values for one-command routes (e.g. rsync [\"-a\",\"--partial\",\"--dry-run\"], scp [\"-p\",\"-r\"], docker cp [\"-a\",\"-L\"], incus file push/pull). One element = one argv token, appended verbatim before src/dst; no shell parsing, no whitelist, no forced defaults — unknown options fail in the native CLI itself. rsync only (SSH endpoints): explicit -e/--rsh overrides the tool's SSH wiring. docker cp: pass -L to follow symlinks (a symlink source like /etc/os-release fails without it). Two-segment cross-endpoint copy uses pullArgv/pushArgv instead."
+			},
+			pullArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PULL half (source endpoint → origin staging) of a two-command cross-endpoint copy (e.g. SSH↔Docker, SSH↔Incus, Docker↔Incus). Mutually exclusive with argv; must be paired with pushArgv. Only options valid for the pull half's CLI."
+			},
+			pushArgv: {
+				type: "array",
+				items: { type: "string" },
+				description: "Options for the PUSH half (origin staging → destination endpoint) of a two-command cross-endpoint copy. Mutually exclusive with argv; must be paired with pullArgv."
+			},
+			verify: {
+				type: "boolean",
+				description: "copy only. Receipts name the verification tier actually performed (D1=A): native CLI routes are \"native-exit-only\" (no independent check — self-verify via oneshot digest commands when needed); the Hub↔local staged lane computes independent SHA-256 digests by default and verify:false skips them (\"not-applicable\"). No hash tier exists on native routes."
+			},
+			mkdir: {
+				type: "boolean",
+				description: "copy only, all routes. Default true: before transfer, one best-effort exec pre-hop ensures the destination's PARENT directory exists (the operand itself is never pre-created — each CLI's own layout semantics stay byte-identical). Receipt created field: true (parent created this call) / false (already existed) / \"n-a\" (skipped or pre-hop unavailable, e.g. docker exec on a stopped container — the native CLI then reports the real error itself). false skips the pre-hop."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						enum: ["copy", "rsync"]
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					receipt: { type: "json" },
+					exit: { oneOf: [{ type: "integer" }, { type: "null" }] },
+					durationMs: { type: "integer" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args, exec) {
+			return transferExecute({
+				driver,
+				getSessionKey
+			}, args, exec);
+		}
+	});
+}
+/** S8 (2026-10-17): copy/rsync render as one formatted line; the full receipt
+* stays in the receipt field — raw-JSON dumps are gone from text. */
+function formatTransferLine(mode, receipt, durationMs) {
+	const r = receipt;
+	const parts = [];
+	if (r.ok === false) parts.push(`✗ ${r.reason ?? "failed"}`);
+	parts.push(`${mode} ${r.src} → ${r.dst}`);
+	if (r.route !== void 0 && r.route !== "") parts.push(`route ${r.route}`);
+	if (r.exits !== void 0) parts.push(`exits [${r.exits.join(",")}]`);
+	else if (r.exit !== void 0) parts.push(`exit ${r.exit}`);
+	if (r.verification !== void 0) parts.push(`verification ${r.verification}`);
+	if (r.created === true) parts.push("created yes");
+	else if (r.created === false) parts.push("created pre-existing");
+	else if (r.created === "n-a") parts.push("created n-a");
+	if (r.cleanup !== void 0 && r.cleanup !== "none-required") parts.push(`cleanup ${r.cleanup}`);
+	if (typeof r.bytes === "number") parts.push(`${r.bytes} bytes / ${r.entries} entries`);
+	parts.push(`${(durationMs / 1e3).toFixed(1)}s`);
+	if (r.note !== void 0 && r.note.length > 0) parts.push(`(${r.note})`);
+	return parts.join(" · ");
+}
+
 //#endregion
 //#region src/remote/agent-registration.ts
+/** The pair a row contributes: execution/PTY and file transfer are separate tools. */
+const TOOL_NAMES = ["remote", "remote_transfer"];
 /** Host listeners attempt once per official creation edge, never on vacancy. */
 function installAgentRemote(ctx, config) {
 	return ctx.on("agent/created", ({ agent }) => {
@@ -4724,12 +5036,14 @@ function installAgentRemote(ctx, config) {
 			...config,
 			getHub: () => agent.ctx.get("superdRemoteTransport")
 		});
-		let unregister;
+		const registered = [];
 		try {
-			unregister = tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id }));
+			registered.push(tools.register(createRemoteTool(driver, { getSessionKey: () => agent.id })));
+			registered.push(tools.register(createRemoteTransferTool(driver, { getSessionKey: () => agent.id })));
 		} catch (error) {
+			for (const undo of registered.splice(0)) undo();
 			driver.dispose();
-			if (error instanceof Error && error.message === "tool \"remote\" is already registered in this scope" && tools.get("remote", agent) !== void 0) return;
+			if (TOOL_NAMES.find((name$1) => error instanceof Error && error.message === `tool "${name$1}" is already registered in this scope` && tools.get(name$1, agent) !== void 0) !== void 0) return;
 			throw error;
 		}
 		const stopService = agent.ctx.on("internal/service", (name$1) => {
@@ -4741,7 +5055,7 @@ function installAgentRemote(ctx, config) {
 		const cleanup = () => {
 			if (disposal) return disposal;
 			disposal = driver.dispose();
-			unregister();
+			for (const undo of registered.splice(0)) undo();
 			stopService();
 			ownerUndo?.();
 			agentUndo?.();
@@ -4797,12 +5111,10 @@ const name = "dashr-remote";
 const inject = [];
 const Config = Schema.object({
 	execTimeoutSec: Schema.natural().min(1).default(120),
-	idleTtlSec: Schema.natural().min(1).default(REMOTE_PTY_IDLE_TTL_SEC),
-	maxOutputChars: Schema.natural().min(1).default(3e4)
+	idleTtlSec: Schema.natural().min(1).default(REMOTE_PTY_IDLE_TTL_SEC)
 }).default({
 	execTimeoutSec: 120,
-	idleTtlSec: REMOTE_PTY_IDLE_TTL_SEC,
-	maxOutputChars: 3e4
+	idleTtlSec: REMOTE_PTY_IDLE_TTL_SEC
 });
 /** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
 const apply = (ctx, config) => {
@@ -4816,4 +5128,4 @@ var plugin_default = {
 };
 
 //#endregion
-export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, Utf16TailRing, apply, checkAbsolute, checkSelection, plugin_default as default, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };
+export { ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, PROCESS_CLEANUP_BOUND_MS, PtySession, Utf16TailRing, apply, buildHubPtyArgv, checkAbsolute, checkSelection, plugin_default as default, disclose, hubPtyAssets, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };