better-dsh 0.2.5 → 0.3.0

package/lib/py-sdk.js

@@ -1,3 +1,3 @@
-import { t as isFlatBindableName } from "./py-sdk-Chvy92MB.js";
+import { t as isFlatBindableName } from "./py-sdk-D7klhpWb.js";
 
 export { isFlatBindableName };

package/lib/remote/plugin.d.ts

@@ -1,5 +1,5 @@
+import { t as Schema } from "../index-DTDXUe6m.js";
 import { Context } from "@deepseek-ai/cordis";
-import z from "@deepseek-ai/schemastery";
 
 //#region src/remote/plugin.d.ts
 
@@ -11,13 +11,13 @@ interface RemoteRowConfig {
   idleTtlSec: number;
   maxOutputChars: number;
 }
-declare const Config: z<RemoteRowConfig>;
+declare const Config: Schema<RemoteRowConfig>;
 /** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
 declare const apply: (ctx: Context, config: RemoteRowConfig) => (() => void);
 declare const _default: {
   name: string;
   inject: string[];
-  Config: z<RemoteRowConfig>;
+  Config: Schema<RemoteRowConfig>;
   apply: (ctx: Context, config: RemoteRowConfig) => (() => void);
 };
 //#endregion

package/lib/remote/plugin.js

@@ -1,11 +1,11 @@
-import { Context } from "@deepseek-ai/cordis";
+import { t as Schema } from "../lib-C8_jXvwA.js";
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
-import z from "@deepseek-ai/schemastery";
 import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
 import { homedir } from "node:os";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { readFile } from "node:fs/promises";
 
 //#region src/remote/oneshot.ts
 /** 单流硬收集帽（4M UTF-16 code units，ASCII≈4MB）：防失控输出吃内存；模型面截断由上层 tailWindow 负责。 */
@@ -158,6 +158,13 @@ function createNonceFrameParser(nonce, events) {
 //#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>` 整条吐给模型。 */
+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;
+}
 const DEFAULT_INIT_TIMEOUT_SEC = 30;
 const INTERRUPT_GRACE_MS = 3e3;
 /** pty 收集内存安全帽（Ruling P15，与 oneshot HARD_CAP 对齐）：模型面只见尾窗，保留尾部。 */
@@ -173,12 +180,18 @@ var PtySession = class {
 	diag = "";
 	inFlight = 0;
 	lastSettleAt = 0;
+	/** 是否曾成功初始化（ready 过）。决定死亡语义：ready 过 → reconnect（留池）；从未 ready → 出池（见 start()）。 */
+	everReady = false;
 	constructor(opts) {
 		this.opts = opts;
 	}
 	get sessionState() {
 		return this.state;
 	}
+	/** 创建来源（spawn 原文）；仅 `byop:<label>` 会话有。 */
+	get origin() {
+		return this.opts.origin;
+	}
 	/** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）+ pid（进程组头，kill 兜底可观测）。 */
 	get snapshot() {
 		return {
@@ -284,12 +297,13 @@ var PtySession = class {
 		} catch {}
 	}
 	async start() {
-		if (this.state === "disposed") throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' was disposed — the pool replaces disposed sessions; this reference is stale`);
+		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`);
 		if (this.startPromise === null) {
 			this.state = "starting";
 			this.startPromise = this.doStart().catch((err) => {
 				this.startPromise = null;
 				this.markDead();
+				if (!this.everReady) this.dispose();
 				throw err;
 			});
 		}
@@ -321,20 +335,21 @@ var PtySession = class {
 		await new Promise((resolve$1, reject) => {
 			const timer = setTimeout(() => {
 				this.killTree();
-				reject(/* @__PURE__ */ new Error(`[E_SESSION_START] remote pty session '${this.opts.key}' did not initialize in ${initTimeoutSec}s` + (this.diag.length > 0 ? `; transport stderr tail: ${this.diag}` : "")));
+				reject(/* @__PURE__ */ new Error(`[E_SESSION_START] remote pty session '${displayKey(this.opts.key)}' did not initialize in ${initTimeoutSec}s` + (this.diag.length > 0 ? `; transport stderr tail: ${this.diag}` : "")));
 			}, initTimeoutSec * 1e3);
 			const waiter = () => {
 				clearTimeout(timer);
-				reject(/* @__PURE__ */ new Error(`[E_SESSION_DIED] remote pty session '${this.opts.key}' died before initializing` + (this.diag.length > 0 ? `; transport stderr tail: ${this.diag}` : "")));
+				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 '${this.opts.key}' disposed during init`));
+					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();
@@ -395,19 +410,26 @@ var PtyPool = class {
 	inspect(key) {
 		return this.sessions.get(key)?.snapshot;
 	}
-	/** roster 面：池内全部会话（key 含 agent 前缀 `${sessionKey}|t:<target>` / `|s:<spawn>`）。 */
+	/** roster 面：池内全部会话（key = `${sessionKey}|t:<target>` 或 `${sessionKey}|p:<label>`）。 */
 	list() {
 		return [...this.sessions.entries()].map(([key, s]) => ({
 			key,
 			snapshot: s.snapshot
 		}));
 	}
-	getOrCreate(key, argv) {
+	/** 池内会话本体（driver 判「有/无 + origin」用；status/roster 面走 inspect/list）。
+	* disposed 视同出池 —— 与 getOrCreate 的替换条件同源，两处不得漂移。 */
+	get(key) {
+		const s = this.sessions.get(key);
+		return s === void 0 || s.sessionState === "disposed" ? void 0 : s;
+	}
+	getOrCreate(key, argv, origin) {
 		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)
 			});
@@ -545,16 +567,21 @@ function renderSession(s) {
 	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);
+}
 
 //#endregion
 //#region src/remote/ssh-config.ts
 /** Per-entry Host-line pattern lists — module-private, so the public entry shape stays exactly as declared. */
 const PATTERNS = /* @__PURE__ */ new WeakMap();
 /** `~` / `~/` prefix → real home directory (IdentityFile only). */
-function expandHome(path) {
-	if (path === "~") return homedir();
-	if (path.startsWith("~/")) return homedir() + path.slice(1);
-	return path;
+function expandHome(path$1) {
+	if (path$1 === "~") return homedir();
+	if (path$1.startsWith("~/")) return homedir() + path$1.slice(1);
+	return path$1;
 }
 function parseSshConfig(text) {
 	const entries = [];
@@ -763,6 +790,8 @@ function buildSpawnArgv(spawnCommand) {
 
 //#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 会话池。 */
 var RemoteDriver = class {
 	pool;
@@ -795,10 +824,11 @@ var RemoteDriver = class {
 	}
 	/** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
 	/**
-	* Ruling P20：裸名先按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
-	* 撞名 ssh 优先，查无 → 默认 ssh 交原生错误）。选择器前缀的 target 不经此路径。
+	* Ruling P20 + PTY 候选表末位：裸名按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
+	* 撞名 ssh 优先），三段全不中再看池内活 PTY label，最后才是默认 ssh（交原生错误）。
+	* 位置即优先级：现有三段一位不挪。选择器前缀的 target 不经此路径。
 	*/
-	async resolveBareName(name$1) {
+	async resolveBareName(name$1, sessionKey, usePtyLabels = true) {
 		const runner = this.opts.rosterRunner ?? runOneShot;
 		const readCfg = this.opts.sshConfigReader ?? (async () => await readFile(join(homedir(), ".ssh", "config"), "utf8"));
 		try {
@@ -831,33 +861,43 @@ var RemoteDriver = class {
 			kind: "incus",
 			container: name$1
 		};
+		if (usePtyLabels && this.pool.get(`${sessionKey}|p:${name$1}`) !== void 0) return {
+			kind: "pty",
+			label: name$1
+		};
 		return {
 			kind: "ssh",
 			host: name$1
 		};
 	}
-	/** Ruling P19：roster = 注意力入口——本地廉价扫描（ssh config/docker ps/incus list + 池内活会话），零拨号。 */
-	async roster() {
-		return await renderRoster(this.pool.list().map(({ key, snapshot }) => {
-			const raw = key.includes("|") ? key.slice(key.indexOf("|") + 1) : key;
-			return {
-				target: raw.startsWith("t:") ? raw.slice(2) : raw.startsWith("s:") ? `spawn:${raw.slice(2)}` : raw,
-				state: snapshot.state,
-				idleSec: snapshot.idleMs !== null ? Math.round(snapshot.idleMs / 1e3) : null
-			};
-		}), this.opts.rosterRunner !== void 0 ? { runner: this.opts.rosterRunner } : {});
+	/** 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 = {}) {
+		const prefix = `${callCtx.sessionKey ?? "no-session"}|`;
+		return await renderRoster(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
+		})), this.opts.rosterRunner !== void 0 ? { runner: this.opts.rosterRunner } : {});
 	}
 	async status(target, callCtx = {}) {
-		const plan = /^(docker|incus|ssh):/.test(target) ? resolveTarget(target) : await this.resolveBareName(target);
-		const head = `${target} — ${plan.kind === "ssh" ? "ssh host" : `${plan.kind} container`}`;
-		const probe = await probeTarget(plan, { runner: this.opts.probeRunner });
-		const key = `${callCtx.sessionKey ?? "no-session"}|t:${target}`;
+		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 resolved = /^(docker|incus|ssh):/.test(target) ? resolveTarget(target) : await this.resolveBareName(target, sessionKey);
+		if (resolved.kind === "pty") return this.ptyStatus(`byop:${resolved.label}`, resolved.label, sessionKey);
 		return [
-			head,
-			renderProbe(probe),
-			renderSession(this.pool.inspect(key))
+			`${target} — ${resolved.kind === "ssh" ? "ssh host" : `${resolved.kind} container`}`,
+			renderProbe(await probeTarget(resolved, { runner: this.opts.probeRunner })),
+			renderSession(this.pool.inspect(`${sessionKey}|t:${target}`))
 		].join("\n");
 	}
+	/** PTY 状态行：纯池内读取，零拨号（label 从来不是可拨目标）。 */
+	ptyStatus(display, label, sessionKey) {
+		return [`${display} — BYO pty session`, renderPtySession(this.pool.inspect(`${sessionKey}|p:${label}`))].join("\n");
+	}
 	/** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径（成功被毒化成失败+双重审计）。 */
 	audit(r) {
 		try {
@@ -867,16 +907,24 @@ var RemoteDriver = class {
 	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: pass exactly one of target or spawn, not both");
-		if (!hasTarget && !hasSpawn) throw new Error("[E_PARAMS] remote: target or spawn is required (e.g. { target: \"dev4\", cmd: \"git status\" })");
+		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");
-		const mode = hasSpawn ? "pty" : params.mode ?? "oneshot";
-		if (hasSpawn) return {
-			mode,
-			display: params.spawn,
-			spawn: params.spawn
-		};
+		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 (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";
 		const direct = /^(docker|incus|ssh):/.test(params.target);
 		return {
 			mode,
@@ -885,9 +933,18 @@ var RemoteDriver = class {
 		};
 	}
 	async execute(params, routing, callCtx) {
-		if (routing.bare !== void 0) routing.plan = await this.resolveBareName(routing.bare);
+		const sessionKey = callCtx.sessionKey ?? "no-session";
+		if (routing.bare !== void 0) {
+			const resolved = await this.resolveBareName(routing.bare, sessionKey, params.mode !== "oneshot");
+			if (resolved.kind === "pty") {
+				routing.pty = { label: resolved.label };
+				routing.mode = "pty";
+				routing.display = `byop:${resolved.label}`;
+			} else routing.plan = resolved;
+		}
 		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
 		const cap = this.opts.maxOutputChars ?? 3e4;
+		if (routing.pty !== void 0) return await this.ptyCall(routing.pty, params, sessionKey, timeoutSec, cap);
 		if (routing.mode === "oneshot") {
 			const r$1 = await runOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(routing.plan, params.cmd), {
 				stdin: params.stdin,
@@ -908,8 +965,8 @@ var RemoteDriver = class {
 				...out$1.truncated !== void 0 ? { truncated: out$1.truncated } : {}
 			};
 		}
-		const argv = routing.spawn !== void 0 ? (this.opts.spawnArgvFor ?? buildSpawnArgv)(routing.spawn) : (this.opts.ptyArgvFor ?? buildPtyArgv)(routing.plan);
-		const key = `${callCtx.sessionKey ?? "no-session"}|${routing.spawn !== void 0 ? `s:${routing.spawn}` : `t:${routing.display}`}`;
+		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, {
 			stdin: params.stdin,
 			timeoutSec
@@ -927,6 +984,38 @@ var RemoteDriver = class {
 			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
 		};
 	}
+	/** 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);
+		return {
+			mode: "pty",
+			target: display,
+			session: display,
+			exit: r.exit,
+			cwd: r.cwd,
+			timedOut: r.timedOut,
+			reconnected: r.reconnected,
+			stdout: out.text,
+			...notice !== void 0 ? { notice } : {},
+			durationMs: r.durationMs,
+			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
+		};
+	}
 	async dispose() {
 		await this.pool.disposeAll();
 	}
@@ -939,15 +1028,15 @@ function createRemoteTool(driver, opts = {}) {
 	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
 	return defineTool({
 		name: "remote",
-		description: "Remote execution over three transports (ssh / docker / incus). Pick the call shape first:\n  {}            → roster: known target names from a local scan (no dialing)\n  {target}      → on-demand status probe of that one target\n  {target, cmd} → run cmd — oneshot by default; mode \"pty\" for a persistent shell\n  {spawn, cmd}  → BYO-PTY: you supply the interactive-shell command\nBare names match by name first (ssh config, then docker, then incus; on a collision ssh wins; unknown names go to ssh and its native error surfaces). \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a transport when you must be explicit. oneshot: stateless `bash -lc`, stdout/stderr separate, the exit code is the remote process's own. pty: one persistent shell per (agent, target) — cwd/env survive across calls, streams merge, Ctrl-C interrupts without killing the session, idle sessions are reaped after 600s (a reconnect notice precedes the fresh shell). Output is tail-truncated at ~30k chars with a \"[truncated: …]\" header — redirect bulk output to a file yourself. `stdin` feeds the command; `timeout` (seconds) interrupts then kills. Native transport errors pass through verbatim — self-correct from them. Background processes must redirect their own output (`cmd > log 2>&1 &`). Status probes report \"reachable\"/\"unreachable — <native error>\" or the factual container state plus the session layer (\"idle Ns\" / \"busy\" / \"none — dials on first exec\"), always probed at call time.",
+		description: "Remote execution over three transports (ssh / docker / incus) plus named persistent BYO shells. Pick the call shape first:\n  {}                                 → roster: known target names from a local scan (no dialing)\n  {target}                           → on-demand status probe of that one target (for \"byop:<label>\": its session state)\n  {target, cmd}                      → run cmd — oneshot by default; mode \"pty\" for a persistent shell\n  {target:\"byop:<label>\", spawn, cmd} → BYO-PTY: create the persistent shell you named <label>\n  {target:\"byop:<label>\", cmd}        → reuse that shell (spawn is only needed to create)\nBYO-PTY labels are yours to choose, and the label alone is the whole reuse mechanism: \"byop:dev3\" is created once with `spawn` (the command that starts an interactive shell, e.g. \"docker exec -it img bash\"), and from then on you address it as {target:\"byop:dev3\", cmd} with no spawn. Repeating the same spawn for a live label is reused and the result tells you to drop it; repeating a *different* spawn is refused with [E_LABEL_CONFLICT] and nothing runs — reuse the label, or pick a new one. A label that was never created, or was reaped after the idle TTL, answers [E_NO_SESSION]: spawn is not retained, so pass it again to re-create. A spawn that fails to come up (e.g. a bad host) leaves nothing behind either — the label stays free, so just retry with a corrected spawn. Bare names match in order — ssh config, then docker, then incus, then a live pty label (on a collision the earlier source wins; a name matching none of them goes to ssh and its native error surfaces). \"byop:<label>\" / \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a channel when you must be explicit. oneshot: stateless `bash -lc`, stdout/stderr separate, the exit code is the remote process's own. pty: one persistent shell per (agent, target) — cwd/env survive across calls, streams merge, Ctrl-C interrupts without killing the session, idle sessions are reaped after 600s (a reconnect notice precedes the fresh shell). Output is tail-truncated at ~30k chars with a \"[truncated: …]\" header — redirect bulk output to a file yourself. `stdin` feeds the command; `timeout` (seconds) interrupts then kills. Native transport errors pass through verbatim — self-correct from them. Background processes must redirect their own output (`cmd > log 2>&1 &`). Status probes report \"reachable\"/\"unreachable — <native error>\" or the factual container state plus the session layer (\"idle Ns\" / \"busy\" / \"none — dials on first exec\"), always probed at call time.",
 		parameters: {
 			target: {
 				type: "string",
-				description: "Bare name / IP / domain matches by name (ssh config, then docker, then incus; collision → ssh). \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a transport. Exactly one of target / spawn."
+				description: "Single entry point. 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."
 			},
 			spawn: {
 				type: "string",
-				description: "BYO-PTY escape hatch: the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). Requires cmd, excludes target; mode is locked to pty; nested hops are dumb pipes (only the innermost bash frames)."
+				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",
@@ -956,7 +1045,7 @@ function createRemoteTool(driver, opts = {}) {
 			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."
+				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",
@@ -991,7 +1080,9 @@ function createRemoteTool(driver, opts = {}) {
 					stderr: { type: "string" },
 					timedOut: { type: "boolean" },
 					reconnected: { type: "boolean" },
-					truncated: { type: "integer" }
+					truncated: { type: "integer" },
+					session: { type: "string" },
+					notice: { type: "string" }
 				}
 			},
 			render: (_args, value) => [{
@@ -1009,7 +1100,7 @@ function createRemoteTool(driver, opts = {}) {
 				if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn is an exec channel — pass cmd (there is nothing to probe for BYO-PTY)");
 				if (!hasTarget) return {
 					kind: "roster",
-					text: await driver.roster(),
+					text: await driver.roster({ sessionKey: getSessionKey(exec) }),
 					exit: null,
 					durationMs: 0
 				};
@@ -1039,6 +1130,8 @@ function createRemoteTool(driver, opts = {}) {
 			if (r.timedOut) v.timedOut = true;
 			if (r.reconnected) v.reconnected = true;
 			if (r.truncated !== void 0) v.truncated = r.truncated;
+			if (r.session !== void 0) v.session = r.session;
+			if (r.notice !== void 0) v.notice = r.notice;
 			return v;
 		}
 	});
@@ -1047,6 +1140,7 @@ function renderValue(v) {
 	if (v.kind === "status" || v.kind === "roster") 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);
 	parts.push(v.text);
 	const secs = ((v.durationMs ?? 0) / 1e3).toFixed(1);
 	const markers = [];
@@ -1054,7 +1148,8 @@ function renderValue(v) {
 	if (v.truncated !== void 0) markers.push(`truncated, original ${v.truncated} chars`);
 	const suffix = markers.length > 0 ? ` · ${markers.join(" · ")}` : "";
 	const cwdTag = typeof v.cwd === "string" && v.cwd.length > 0 ? ` · cwd ${v.cwd}` : "";
-	parts.push(`[exit ${v.exit} · ${secs}s${suffix}${cwdTag}]`);
+	const sessionTag = typeof v.session === "string" && v.session.length > 0 ? ` · ${v.session}` : "";
+	parts.push(`[exit ${v.exit} · ${secs}s${suffix}${cwdTag}${sessionTag}]`);
 	if (v.stderr !== void 0 && v.stderr.length > 0) parts.push("[stderr]", v.stderr);
 	return parts.join("\n");
 }
@@ -1063,10 +1158,10 @@ function renderValue(v) {
 //#region src/remote/plugin.ts
 const name = "dashr-remote";
 const inject = [];
-const Config = z.object({
-	execTimeoutSec: z.natural().min(1).default(120),
-	idleTtlSec: z.natural().min(1).default(600),
-	maxOutputChars: z.natural().min(1).default(3e4)
+const Config = Schema.object({
+	execTimeoutSec: Schema.natural().min(1).default(120),
+	idleTtlSec: Schema.natural().min(1).default(600),
+	maxOutputChars: Schema.natural().min(1).default(3e4)
 }).default({
 	execTimeoutSec: 120,
 	idleTtlSec: 600,

package/lib/url-schemes/index.d.ts

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