@linxin666/dsh-ssh 0.4.2 → 0.4.4

package/lib/index.js

@@ -1673,6 +1673,265 @@ var SshEngine = class {
 	}
 };
 //#endregion
+//#region src/engine/terminal-sessions.ts
+/**
+* Host-side terminal sessions for the web terminal.
+*
+* The PTY shell is owned here, not by the browser view: a view can detach
+* (panel switch, page unmount, a dropped socket) and reattach by session id
+* without tearing the remote shell down, which is what makes the terminal
+* survival property the old DOM takeover used to provide. A session with no
+* attached socket is reaped after an idle window, and an exited one is kept
+* for a short grace window so a reattaching view still sees the final screen.
+*/
+/** Pause the shell when an attached socket's send buffer exceeds this… */
+const BACKPRESSURE_HIGH_WATER = 1024 * 1024;
+/** …and resume once every attached socket drains below this. */
+const BACKPRESSURE_LOW_WATER = 512 * 1024;
+/** Scrollback retained for a reattaching view (bytes of UTF-8 output). */
+const DEFAULT_MAX_BUFFER_BYTES = 256 * 1024;
+/** A detached session is reaped after this long. */
+const DEFAULT_IDLE_MS = 600 * 1e3;
+/** An exited session is kept this long for a reattaching view. */
+const DEFAULT_EXIT_GRACE_MS = 60 * 1e3;
+/**
+* The host's terminal session table: open one session per connect, attach any
+* number of sockets, and keep the shell alive across detach.
+*/
+var TerminalSessionRegistry = class {
+	sessions = /* @__PURE__ */ new Map();
+	deps;
+	maxBufferBytes;
+	idleMs;
+	exitGraceMs;
+	constructor(deps) {
+		this.deps = deps;
+		this.maxBufferBytes = deps.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+		this.idleMs = deps.idleMs ?? DEFAULT_IDLE_MS;
+		this.exitGraceMs = deps.exitGraceMs ?? DEFAULT_EXIT_GRACE_MS;
+	}
+	/** Open a new session for the alias and attach the requesting socket to it. */
+	async open(ws, alias, size) {
+		const session = {
+			id: randomBytes(9).toString("hex"),
+			alias,
+			sockets: /* @__PURE__ */ new Set(),
+			buffer: [],
+			bufferBytes: 0,
+			exited: false
+		};
+		this.sessions.set(session.id, session);
+		this.bind(ws, session);
+		try {
+			const shell = await this.deps.openShell(alias, size, this.keyboardInteractive(session));
+			if (!this.sessions.has(session.id)) {
+				shell.close();
+				return;
+			}
+			session.shell = shell;
+			shell.onData = (data) => {
+				this.pushOutput(session, data.toString("utf8"));
+			};
+			shell.onExit = (code, error) => {
+				this.finish(session, code, error);
+			};
+			this.send(session, {
+				type: "ready",
+				alias,
+				sessionId: session.id
+			});
+		} catch (error) {
+			this.sessions.delete(session.id);
+			this.send(session, {
+				type: "exit",
+				code: null,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	/**
+	* Attach a socket to an existing session, replaying its scrollback first.
+	* @returns false when the session is unknown (expired or already reaped).
+	*/
+	attach(ws, sessionId, size) {
+		const session = this.sessions.get(sessionId);
+		if (session === void 0) return false;
+		this.bind(ws, session);
+		this.clearReap(session);
+		for (const chunk of session.buffer) this.sendTo(session, ws, {
+			type: "output",
+			data: chunk
+		});
+		this.sendTo(session, ws, {
+			type: "ready",
+			alias: session.alias,
+			sessionId: session.id
+		});
+		if (session.exited) {
+			this.sendTo(session, ws, {
+				type: "exit",
+				code: session.exit?.code ?? null,
+				error: session.exit?.error
+			});
+			this.scheduleReap(session, this.exitGraceMs);
+		} else {
+			session.shell?.resize(Math.max(2, size.cols), Math.max(1, size.rows));
+			session.shell?.resume();
+		}
+		return true;
+	}
+	/** End every session (host teardown, plugin dispose). */
+	dispose() {
+		for (const session of [...this.sessions.values()]) this.end(session, false);
+		this.sessions.clear();
+	}
+	/** Number of live sessions (introspection for tests and diagnostics). */
+	size() {
+		return this.sessions.size;
+	}
+	/** Wire one socket's frames and lifecycle onto a session. */
+	bind(ws, session) {
+		session.sockets.add(ws);
+		ws.on("message", (data) => {
+			let frame;
+			try {
+				frame = JSON.parse(String(data));
+			} catch {
+				return;
+			}
+			if (frame.type === "input") session.shell?.send(frame.data ?? "");
+			else if (frame.type === "resize") session.shell?.resize(Math.max(2, frame.cols ?? 80), Math.max(1, frame.rows ?? 24));
+			else if (frame.type === "auth_response") {
+				const finish = session.pendingAuthFinish;
+				session.pendingAuthFinish = void 0;
+				try {
+					finish?.(frame.responses ?? []);
+				} catch {}
+			} else if (frame.type === "close") this.end(session, true);
+			else if (frame.type === "detach") this.detach(ws);
+		});
+		ws.on("close", () => {
+			this.detach(ws);
+		});
+		ws.on("error", () => {
+			this.detach(ws);
+		});
+	}
+	/** Remove a socket from its session, keeping the shell alive. */
+	detach(ws) {
+		for (const session of this.sessions.values()) {
+			if (!session.sockets.delete(ws)) continue;
+			if (session.sockets.size === 0) this.scheduleReap(session, session.exited ? this.exitGraceMs : this.idleMs);
+			return;
+		}
+	}
+	/** End the session a socket is attached to (explicit close from the view). */
+	end(session, notify) {
+		this.clearReap(session);
+		if (this.sessions.delete(session.id) && notify) {
+			if (session.pendingAuthFinish !== void 0) {
+				const finish = session.pendingAuthFinish;
+				session.pendingAuthFinish = void 0;
+				try {
+					finish([]);
+				} catch {}
+			}
+		}
+		try {
+			session.shell?.close();
+		} catch {}
+	}
+	/** Mark a session exited and keep it briefly so a reattaching view sees it. */
+	finish(session, code, error) {
+		if (session.exited) return;
+		session.exited = true;
+		session.exit = {
+			code,
+			error
+		};
+		this.send(session, {
+			type: "exit",
+			code,
+			error
+		});
+		for (const ws of [...session.sockets]) {
+			session.sockets.delete(ws);
+			try {
+				ws.close(1e3);
+			} catch {}
+		}
+		this.scheduleReap(session, this.exitGraceMs);
+	}
+	/** Append output to the replay buffer, trimmed to the byte cap. */
+	pushOutput(session, data) {
+		session.buffer.push(data);
+		session.bufferBytes += Buffer.byteLength(data);
+		while (session.bufferBytes > this.maxBufferBytes && session.buffer.length > 1) {
+			const dropped = session.buffer.shift();
+			session.bufferBytes -= Buffer.byteLength(dropped ?? "");
+		}
+		this.send(session, {
+			type: "output",
+			data
+		});
+	}
+	/** Broadcast one frame to every attached socket, honoring backpressure. */
+	send(session, frame) {
+		for (const ws of session.sockets) this.sendTo(session, ws, frame);
+		this.applyBackpressure(session);
+	}
+	sendTo(session, ws, frame) {
+		if (ws.readyState !== WebSocket.OPEN) return;
+		try {
+			ws.send(JSON.stringify(frame));
+		} catch {}
+	}
+	/** Pause while any attached socket is backed up; resume once all drained. */
+	applyBackpressure(session) {
+		const shell = session.shell;
+		if (shell === void 0) return;
+		let high = false;
+		let low = true;
+		for (const ws of session.sockets) {
+			if (ws.bufferedAmount > BACKPRESSURE_HIGH_WATER) high = true;
+			if (ws.bufferedAmount > BACKPRESSURE_LOW_WATER) low = false;
+		}
+		if (high) shell.pause();
+		else if (low) shell.resume();
+	}
+	/** Answer a keyboard-interactive challenge through whoever is attached. */
+	keyboardInteractive(session) {
+		return (name, instructions, _lang, prompts, finish) => {
+			session.pendingAuthFinish = finish;
+			this.send(session, {
+				type: "auth_prompt",
+				name,
+				instructions,
+				prompts: prompts.map((p) => ({
+					prompt: p.prompt,
+					echo: p.echo
+				}))
+			});
+		};
+	}
+	scheduleReap(session, delayMs) {
+		this.clearReap(session);
+		const timer = setTimeout(() => {
+			session.reapTimer = void 0;
+			if (session.sockets.size > 0) return;
+			this.end(session, false);
+		}, delayMs);
+		timer.unref?.();
+		session.reapTimer = timer;
+	}
+	clearReap(session) {
+		if (session.reapTimer !== void 0) {
+			clearTimeout(session.reapTimer);
+			session.reapTimer = void 0;
+		}
+	}
+};
+//#endregion
 //#region src/http.ts
 /** Default body cap for readJsonBody: 64 KiB. */
 const DEFAULT_JSON_BODY_MAX_BYTES = 64 * 1024;
@@ -1806,10 +2065,6 @@ const MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024;
 * frames (the webserver hands us the raw upgraded socket).
 */
 const terminalWss = new WebSocketServer({ noServer: true });
-/** Pause the shell when the socket's send buffer exceeds this… */
-const BACKPRESSURE_HIGH_WATER = 1024 * 1024;
-/** …and resume once it drains below this. */
-const BACKPRESSURE_LOW_WATER = 512 * 1024;
 /** URL query helper (first value, decoded). */
 function queryParam(url, name) {
 	const value = url.searchParams.get(name);
@@ -1840,391 +2095,393 @@ function makeRoutes(deps) {
 		}
 		return true;
 	};
-	return {
-		routes: [
-			{
-				kind: "exact",
-				path: SSH_API.hosts,
-				handler: async (req, res) => {
-					const method = req.method ?? "GET";
-					if (!isLoopbackRequest(req)) {
-						writeJson(res, 403, { error: "forbidden: loopback-only" });
-						return;
-					}
-					const url = new URL(req.url ?? "/", "http://localhost");
-					if (method === "GET") {
-						writeJson(res, 200, { hosts: engine.list(queryParam(url, "query")) });
-						return;
-					}
-					if (method === "POST") {
-						const body = await readJsonBody(req);
-						if (body === null) {
-							writeJson(res, 400, { error: "invalid JSON body" });
-							return;
-						}
-						try {
-							const entry = store.create(body);
-							writeJson(res, 201, { host: store.summarize(entry) });
-						} catch (error) {
-							writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
-						}
-						return;
-					}
-					if (method !== "PATCH" && method !== "DELETE") {
-						writeJson(res, 405, { error: `method not allowed: ${method}` });
-						return;
-					}
-					const alias = queryParam(url, "alias");
-					if (alias === void 0 || alias === "") {
-						writeJson(res, 400, { error: "alias query parameter is required" });
-						return;
-					}
-					if (method === "PATCH") {
-						const body = await readJsonBody(req);
-						if (body === null) {
-							writeJson(res, 400, { error: "invalid JSON body" });
-							return;
-						}
-						try {
-							const entry = store.update(alias, body);
-							const patch = body;
-							if ([
-								"host",
-								"port",
-								"user",
-								"auth",
-								"proxyJump",
-								"proxyCommand"
-							].some((key) => patch[key] !== void 0)) engine.dropAlias(alias);
-							writeJson(res, 200, { host: store.summarize(entry) });
-						} catch (error) {
-							writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
-						}
-						return;
-					}
-					if (method === "DELETE") {
-						try {
-							engine.dropAlias(alias);
-							store.delete(alias);
-							writeJson(res, 200, { ok: true });
-						} catch (error) {
-							writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
-						}
-						return;
-					}
-					writeJson(res, 405, { error: `method not allowed: ${method}` });
+	const routes = [
+		{
+			kind: "exact",
+			path: SSH_API.hosts,
+			handler: async (req, res) => {
+				const method = req.method ?? "GET";
+				if (!isLoopbackRequest(req)) {
+					writeJson(res, 403, { error: "forbidden: loopback-only" });
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.importSshConfig,
-				handler: async (req, res) => {
-					if (!guard(req, res, "POST")) return;
-					try {
-						writeJson(res, 200, { result: store.importFromSshConfig() });
-					} catch (error) {
-						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
-					}
+				const url = new URL(req.url ?? "/", "http://localhost");
+				if (method === "GET") {
+					writeJson(res, 200, { hosts: engine.list(queryParam(url, "query")) });
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.test,
-				handler: async (req, res) => {
-					if (!guard(req, res, "POST")) return;
+				if (method === "POST") {
 					const body = await readJsonBody(req);
-					const alias = typeof body?.alias === "string" ? body.alias : "";
-					if (alias === "") {
-						writeJson(res, 400, { error: "alias is required" });
+					if (body === null) {
+						writeJson(res, 400, { error: "invalid JSON body" });
 						return;
 					}
 					try {
-						writeJson(res, 200, { result: await engine.test(alias) });
+						const entry = store.create(body);
+						writeJson(res, 201, { host: store.summarize(entry) });
 					} catch (error) {
-						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
 					}
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.exec,
-				handler: async (req, res) => {
-					if (!guard(req, res, "POST")) return;
+				if (method !== "PATCH" && method !== "DELETE") {
+					writeJson(res, 405, { error: `method not allowed: ${method}` });
+					return;
+				}
+				const alias = queryParam(url, "alias");
+				if (alias === void 0 || alias === "") {
+					writeJson(res, 400, { error: "alias query parameter is required" });
+					return;
+				}
+				if (method === "PATCH") {
 					const body = await readJsonBody(req);
-					const alias = typeof body?.alias === "string" ? body.alias : "";
-					const command = typeof body?.command === "string" ? body.command : "";
-					if (alias === "" || command === "") {
-						writeJson(res, 400, { error: "alias and command are required" });
+					if (body === null) {
+						writeJson(res, 400, { error: "invalid JSON body" });
 						return;
 					}
-					const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
 					try {
-						writeJson(res, 200, { result: await engine.exec(alias, command, timeoutMs) });
+						const entry = store.update(alias, body);
+						const patch = body;
+						if ([
+							"host",
+							"port",
+							"user",
+							"auth",
+							"proxyJump",
+							"proxyCommand"
+						].some((key) => patch[key] !== void 0)) engine.dropAlias(alias);
+						writeJson(res, 200, { host: store.summarize(entry) });
 					} catch (error) {
-						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
 					}
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.cluster,
-				handler: async (req, res) => {
-					if (!guard(req, res, "POST")) return;
-					const body = await readJsonBody(req);
-					const command = typeof body?.command === "string" ? body.command : "";
-					if (command === "") {
-						writeJson(res, 400, { error: "command is required" });
-						return;
-					}
-					const aliases = Array.isArray(body?.aliases) ? body.aliases.filter((x) => typeof x === "string") : void 0;
-					const tags = Array.isArray(body?.tags) ? body.tags.filter((x) => typeof x === "string") : void 0;
-					const environment = typeof body?.environment === "string" ? body.environment : void 0;
-					const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
-					const maxWorkers = typeof body?.maxWorkers === "number" ? body.maxWorkers : void 0;
-					const hasAliases = aliases?.some((alias) => alias.trim() !== "") === true;
-					const hasEnvironment = typeof environment === "string" && environment.trim() !== "";
-					const hasTags = tags?.some((tag) => tag.trim() !== "") === true;
-					if (!hasAliases && !hasEnvironment && !hasTags) {
-						writeJson(res, 400, { error: "ssh_cluster requires aliases, environment, or tags to limit the target set" });
-						return;
-					}
+				if (method === "DELETE") {
 					try {
-						writeJson(res, 200, { results: await engine.cluster({
-							command,
-							aliases,
-							environment,
-							tags,
-							timeoutMs,
-							maxWorkers
-						}) });
+						engine.dropAlias(alias);
+						store.delete(alias);
+						writeJson(res, 200, { ok: true });
 					} catch (error) {
-						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
 					}
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.ls,
-				handler: async (req, res) => {
-					if (!guard(req, res, "GET")) return;
-					const url = new URL(req.url ?? "/", "http://localhost");
-					const alias = queryParam(url, "alias");
-					const path = queryParam(url, "path") ?? "/";
-					if (alias === void 0 || alias === "") {
-						writeJson(res, 400, { error: "alias query parameter is required" });
+				writeJson(res, 405, { error: `method not allowed: ${method}` });
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.importSshConfig,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, { result: store.importFromSshConfig() });
+				} catch (error) {
+					writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.test,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const alias = typeof body?.alias === "string" ? body.alias : "";
+				if (alias === "") {
+					writeJson(res, 400, { error: "alias is required" });
+					return;
+				}
+				try {
+					writeJson(res, 200, { result: await engine.test(alias) });
+				} catch (error) {
+					writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.exec,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const alias = typeof body?.alias === "string" ? body.alias : "";
+				const command = typeof body?.command === "string" ? body.command : "";
+				if (alias === "" || command === "") {
+					writeJson(res, 400, { error: "alias and command are required" });
+					return;
+				}
+				const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
+				try {
+					writeJson(res, 200, { result: await engine.exec(alias, command, timeoutMs) });
+				} catch (error) {
+					writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.cluster,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const command = typeof body?.command === "string" ? body.command : "";
+				if (command === "") {
+					writeJson(res, 400, { error: "command is required" });
+					return;
+				}
+				const aliases = Array.isArray(body?.aliases) ? body.aliases.filter((x) => typeof x === "string") : void 0;
+				const tags = Array.isArray(body?.tags) ? body.tags.filter((x) => typeof x === "string") : void 0;
+				const environment = typeof body?.environment === "string" ? body.environment : void 0;
+				const timeoutMs = typeof body?.timeoutMs === "number" ? body.timeoutMs : void 0;
+				const maxWorkers = typeof body?.maxWorkers === "number" ? body.maxWorkers : void 0;
+				const hasAliases = aliases?.some((alias) => alias.trim() !== "") === true;
+				const hasEnvironment = typeof environment === "string" && environment.trim() !== "";
+				const hasTags = tags?.some((tag) => tag.trim() !== "") === true;
+				if (!hasAliases && !hasEnvironment && !hasTags) {
+					writeJson(res, 400, { error: "ssh_cluster requires aliases, environment, or tags to limit the target set" });
+					return;
+				}
+				try {
+					writeJson(res, 200, { results: await engine.cluster({
+						command,
+						aliases,
+						environment,
+						tags,
+						timeoutMs,
+						maxWorkers
+					}) });
+				} catch (error) {
+					writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.ls,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const url = new URL(req.url ?? "/", "http://localhost");
+				const alias = queryParam(url, "alias");
+				const path = queryParam(url, "path") ?? "/";
+				if (alias === void 0 || alias === "") {
+					writeJson(res, 400, { error: "alias query parameter is required" });
+					return;
+				}
+				try {
+					writeJson(res, 200, { entries: await engine.ls(alias, path) });
+				} catch (error) {
+					writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.tunnel,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const action = typeof body?.action === "string" ? body.action : "";
+				if (action === "list") {
+					writeJson(res, 200, { tunnels: engine.listTunnels() });
+					return;
+				}
+				if (action === "start") {
+					const alias = typeof body?.alias === "string" ? body.alias : "";
+					const remotePort = typeof body?.remotePort === "number" ? body.remotePort : void 0;
+					if (alias === "" || remotePort === void 0) {
+						writeJson(res, 400, { error: "alias and remotePort are required" });
 						return;
 					}
 					try {
-						writeJson(res, 200, { entries: await engine.ls(alias, path) });
+						writeJson(res, 200, { tunnel: await engine.startTunnel(alias, {
+							remotePort,
+							remoteHost: typeof body?.remoteHost === "string" && body.remoteHost !== "" ? body.remoteHost : void 0,
+							localPort: typeof body?.localPort === "number" ? body.localPort : void 0
+						}) });
 					} catch (error) {
-						writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+						writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
 					}
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.tunnel,
-				handler: async (req, res) => {
-					if (!guard(req, res, "POST")) return;
-					const body = await readJsonBody(req);
-					const action = typeof body?.action === "string" ? body.action : "";
-					if (action === "list") {
-						writeJson(res, 200, { tunnels: engine.listTunnels() });
+				if (action === "stop") {
+					const id = typeof body?.tunnelId === "string" ? body.tunnelId : "";
+					if (id === "") {
+						writeJson(res, 400, { error: "tunnelId is required" });
 						return;
 					}
-					if (action === "start") {
-						const alias = typeof body?.alias === "string" ? body.alias : "";
-						const remotePort = typeof body?.remotePort === "number" ? body.remotePort : void 0;
-						if (alias === "" || remotePort === void 0) {
-							writeJson(res, 400, { error: "alias and remotePort are required" });
-							return;
-						}
-						try {
-							writeJson(res, 200, { tunnel: await engine.startTunnel(alias, {
-								remotePort,
-								remoteHost: typeof body?.remoteHost === "string" && body.remoteHost !== "" ? body.remoteHost : void 0,
-								localPort: typeof body?.localPort === "number" ? body.localPort : void 0
-							}) });
-						} catch (error) {
-							writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
-						}
-						return;
-					}
-					if (action === "stop") {
-						const id = typeof body?.tunnelId === "string" ? body.tunnelId : "";
-						if (id === "") {
-							writeJson(res, 400, { error: "tunnelId is required" });
-							return;
-						}
-						writeJson(res, 200, { ok: engine.stopTunnel(id) });
-						return;
-					}
-					if (action === "stop-all") {
-						const alias = typeof body?.alias === "string" ? body.alias : void 0;
-						writeJson(res, 200, { stopped: engine.stopAllTunnels(alias === "" ? void 0 : alias) });
-						return;
-					}
-					writeJson(res, 400, { error: `unknown action '${action}'` });
+					writeJson(res, 200, { ok: engine.stopTunnel(id) });
+					return;
 				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.upload,
-				handler: async (req, res) => {
-					if (!guard(req, res, "POST")) return;
-					const url = new URL(req.url ?? "/", "http://localhost");
-					const alias = queryParam(url, "alias");
-					const remotePath = queryParam(url, "remotePath");
-					if (alias === void 0 || remotePath === void 0) {
-						writeJson(res, 400, { error: "alias and remotePath query parameters are required" });
-						return;
-					}
-					const declared = Number(req.headers["content-length"]);
-					if (Number.isFinite(declared) && declared > maxUploadBytes) {
-						writeJson(res, 413, { error: "upload body too large" });
-						return;
-					}
-					res.writeHead(200, {
-						"content-type": "application/x-ndjson; charset=utf-8",
-						"cache-control": "no-cache",
-						"referrer-policy": "no-referrer"
+				if (action === "stop-all") {
+					const alias = typeof body?.alias === "string" ? body.alias : void 0;
+					writeJson(res, 200, { stopped: engine.stopAllTunnels(alias === "" ? void 0 : alias) });
+					return;
+				}
+				writeJson(res, 400, { error: `unknown action '${action}'` });
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.upload,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const url = new URL(req.url ?? "/", "http://localhost");
+				const alias = queryParam(url, "alias");
+				const remotePath = queryParam(url, "remotePath");
+				if (alias === void 0 || remotePath === void 0) {
+					writeJson(res, 400, { error: "alias and remotePath query parameters are required" });
+					return;
+				}
+				const declared = Number(req.headers["content-length"]);
+				if (Number.isFinite(declared) && declared > maxUploadBytes) {
+					writeJson(res, 413, { error: "upload body too large" });
+					return;
+				}
+				res.writeHead(200, {
+					"content-type": "application/x-ndjson; charset=utf-8",
+					"cache-control": "no-cache",
+					"referrer-policy": "no-referrer"
+				});
+				const emit = (line) => {
+					try {
+						res.write(JSON.stringify(line) + "\n");
+					} catch {}
+				};
+				const tmp = join(staging, `upload-${randomBytes(6).toString("hex")}`);
+				const sink = createWriteStream(tmp, { mode: 384 });
+				let settled = false;
+				const fail = (error) => {
+					if (settled) return;
+					settled = true;
+					emit({
+						type: "result",
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
 					});
-					const emit = (line) => {
-						try {
-							res.write(JSON.stringify(line) + "\n");
-						} catch {}
-					};
-					const tmp = join(staging, `upload-${randomBytes(6).toString("hex")}`);
-					const sink = createWriteStream(tmp, { mode: 384 });
-					let settled = false;
-					const fail = (error) => {
-						if (settled) return;
-						settled = true;
-						emit({
-							type: "result",
-							ok: false,
-							error: error instanceof Error ? error.message : String(error)
-						});
-						const cleanup = () => {
-							unlink(tmp).catch(() => void 0).finally(() => {
-								try {
-									res.end();
-								} catch {}
-							});
-						};
-						if (sink.destroyed) cleanup();
-						else {
-							sink.once("close", cleanup);
+					const cleanup = () => {
+						unlink(tmp).catch(() => void 0).finally(() => {
 							try {
-								sink.destroy();
-							} catch {
-								cleanup();
-							}
-						}
+								res.end();
+							} catch {}
+						});
 					};
-					const done = () => {
-						if (settled) return;
-						settled = true;
+					if (sink.destroyed) cleanup();
+					else {
+						sink.once("close", cleanup);
 						try {
-							res.end();
-						} catch {}
-					};
-					sink.on("error", (error) => fail(error));
-					req.on("error", (error) => fail(error));
-					req.on("aborted", () => fail("upload aborted by the client"));
-					res.on("error", () => fail("response stream closed"));
-					res.on("close", () => {
-						if (!res.writableEnded) fail("connection closed");
-					});
-					let received = 0;
-					let capped = false;
-					req.on("data", (chunk) => {
-						received += chunk.byteLength;
-						if (received > maxUploadBytes && !capped) {
-							capped = true;
-							fail("upload body too large");
-							res.on("finish", () => {
-								try {
-									req.destroy();
-								} catch {}
-							});
-							req.resume();
+							sink.destroy();
+						} catch {
+							cleanup();
 						}
-					});
-					req.pipe(sink);
-					sink.on("finish", async () => {
-						if (settled) return;
-						emit({
-							type: "progress",
-							progress: {
-								phase: "connecting",
-								file: remotePath,
-								transferred: 0,
-								total: 0,
-								percent: 0
-							}
+					}
+				};
+				const done = () => {
+					if (settled) return;
+					settled = true;
+					try {
+						res.end();
+					} catch {}
+				};
+				sink.on("error", (error) => fail(error));
+				req.on("error", (error) => fail(error));
+				req.on("aborted", () => fail("upload aborted by the client"));
+				res.on("error", () => fail("response stream closed"));
+				res.on("close", () => {
+					if (!res.writableEnded) fail("connection closed");
+				});
+				let received = 0;
+				let capped = false;
+				req.on("data", (chunk) => {
+					received += chunk.byteLength;
+					if (received > maxUploadBytes && !capped) {
+						capped = true;
+						fail("upload body too large");
+						res.on("finish", () => {
+							try {
+								req.destroy();
+							} catch {}
 						});
-						try {
-							const outcome = await engine.upload(alias, tmp, remotePath, false, (progress) => emit({
-								type: "progress",
-								progress
-							}));
-							emit({
-								type: "result",
-								ok: true,
-								transferredBytes: outcome.bytes
-							});
-						} catch (error) {
-							emit({
-								type: "result",
-								ok: false,
-								error: error instanceof Error ? error.message : String(error)
-							});
-						} finally {
-							await unlink(tmp).catch(() => void 0);
-							done();
+						req.resume();
+					}
+				});
+				req.pipe(sink);
+				sink.on("finish", async () => {
+					if (settled) return;
+					emit({
+						type: "progress",
+						progress: {
+							phase: "connecting",
+							file: remotePath,
+							transferred: 0,
+							total: 0,
+							percent: 0
 						}
 					});
-				}
-			},
-			{
-				kind: "exact",
-				path: SSH_API.download,
-				handler: async (req, res) => {
-					if (!guard(req, res, "GET")) return;
-					const url = new URL(req.url ?? "/", "http://localhost");
-					const alias = queryParam(url, "alias");
-					const remotePath = queryParam(url, "remotePath");
-					if (alias === void 0 || remotePath === void 0) {
-						writeJson(res, 400, { error: "alias and remotePath query parameters are required" });
-						return;
-					}
-					const tmp = join(staging, `download-${randomBytes(6).toString("hex")}`);
 					try {
-						closeSync(openSync(tmp, "w", 384));
-						const outcome = await engine.download(alias, remotePath, tmp);
-						res.writeHead(200, {
-							"content-type": "application/octet-stream",
-							"content-length": String(outcome.bytes),
-							"content-disposition": `attachment; filename="${basename(remotePath).replace(/"/g, "")}"`,
-							"referrer-policy": "no-referrer"
-						});
-						await new Promise((resolve, reject) => {
-							const source = createReadStream(tmp);
-							source.on("error", reject);
-							res.on("error", reject);
-							source.pipe(res);
-							source.on("end", resolve);
+						const outcome = await engine.upload(alias, tmp, remotePath, false, (progress) => emit({
+							type: "progress",
+							progress
+						}));
+						emit({
+							type: "result",
+							ok: true,
+							transferredBytes: outcome.bytes
 						});
 					} catch (error) {
-						if (!res.headersSent) writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
-						else res.destroy();
+						emit({
+							type: "result",
+							ok: false,
+							error: error instanceof Error ? error.message : String(error)
+						});
 					} finally {
 						await unlink(tmp).catch(() => void 0);
+						done();
 					}
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: SSH_API.download,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const url = new URL(req.url ?? "/", "http://localhost");
+				const alias = queryParam(url, "alias");
+				const remotePath = queryParam(url, "remotePath");
+				if (alias === void 0 || remotePath === void 0) {
+					writeJson(res, 400, { error: "alias and remotePath query parameters are required" });
+					return;
+				}
+				const tmp = join(staging, `download-${randomBytes(6).toString("hex")}`);
+				try {
+					closeSync(openSync(tmp, "w", 384));
+					const outcome = await engine.download(alias, remotePath, tmp);
+					res.writeHead(200, {
+						"content-type": "application/octet-stream",
+						"content-length": String(outcome.bytes),
+						"content-disposition": `attachment; filename="${basename(remotePath).replace(/"/g, "")}"`,
+						"referrer-policy": "no-referrer"
+					});
+					await new Promise((resolve, reject) => {
+						const source = createReadStream(tmp);
+						source.on("error", reject);
+						res.on("error", reject);
+						source.pipe(res);
+						source.on("end", resolve);
+					});
+				} catch (error) {
+					if (!res.headersSent) writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+					else res.destroy();
+				} finally {
+					await unlink(tmp).catch(() => void 0);
 				}
 			}
-		],
+		}
+	];
+	const terminalSessions = new TerminalSessionRegistry({ openShell: (alias, size, onKeyboardInteractive) => engine.openShell(alias, size, onKeyboardInteractive) });
+	return {
+		routes,
 		upgrade: {
 			path: SSH_API.terminal,
 			handler: (req, socket, head) => {
@@ -2235,129 +2492,39 @@ function makeRoutes(deps) {
 				}
 				const url = new URL(req.url ?? "/", "http://localhost");
 				const alias = queryParam(url, "alias");
-				if (alias === void 0) {
+				const sessionId = queryParam(url, "session");
+				if (alias === void 0 && sessionId === void 0) {
 					socket.write("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
 					socket.destroy();
 					return;
 				}
 				const cols = Number.parseInt(queryParam(url, "cols") ?? "80", 10);
 				const rows = Number.parseInt(queryParam(url, "rows") ?? "24", 10);
+				const size = {
+					cols: Number.isFinite(cols) ? cols : 80,
+					rows: Number.isFinite(rows) ? rows : 24
+				};
 				terminalWss.handleUpgrade(req, socket, head, (ws) => {
-					let session;
-					let closed = false;
-					let paused = false;
-					let pendingAuthFinish;
-					const resume = () => {
-						if (paused && ws.bufferedAmount < BACKPRESSURE_LOW_WATER) {
-							paused = false;
-							session?.resume();
-						}
-					};
-					const sendFrame = (frame) => {
-						if (closed || ws.readyState !== WebSocket.OPEN) return;
-						ws.send(JSON.stringify(frame), resume);
-						if (!paused && ws.bufferedAmount > BACKPRESSURE_HIGH_WATER) {
-							paused = true;
-							session?.pause();
-						}
-					};
-					const closeSession = () => {
-						if (pendingAuthFinish !== void 0) {
-							const fn = pendingAuthFinish;
-							pendingAuthFinish = void 0;
-							try {
-								fn([]);
-							} catch {}
-						}
-						const opened = session;
-						session = void 0;
-						if (opened !== void 0) opened.close();
-					};
-					const onKeyboardInteractive = (name, instructions, _lang, prompts, finish) => {
-						const entry = store.find(alias);
-						if (entry?.auth.kind === "password" && entry.auth.password !== void 0 && prompts.length > 0 && prompts.every((p) => /password/i.test(p.prompt))) {
-							const password = entry.auth.password;
-							finish(prompts.map(() => password));
-							return;
-						}
-						pendingAuthFinish = finish;
-						sendFrame({
-							type: "auth_prompt",
-							name,
-							instructions,
-							prompts: prompts.map((p) => ({
-								prompt: p.prompt,
-								echo: p.echo
-							}))
-						});
-					};
-					engine.openShell(alias, {
-						cols: Number.isFinite(cols) ? cols : 80,
-						rows: Number.isFinite(rows) ? rows : 24
-					}, onKeyboardInteractive).then((opened) => {
-						if (ws.readyState !== WebSocket.OPEN) {
-							opened.close();
-							return;
-						}
-						session = opened;
-						sendFrame({
-							type: "ready",
-							alias
-						});
-						opened.onData = (data) => sendFrame({
-							type: "output",
-							data: data.toString("utf8")
-						});
-						opened.onExit = (code, error) => {
-							sendFrame({
-								type: "exit",
-								code,
-								error
-							});
-							closed = true;
-							try {
-								ws.close(1e3);
-							} catch {}
-						};
-					}).catch((error) => {
-						sendFrame({
+					if (sessionId !== void 0) {
+						if (terminalSessions.attach(ws, sessionId, size)) return;
+						const expired = {
 							type: "exit",
 							code: null,
-							error: error instanceof Error ? error.message : String(error)
-						});
-						closed = true;
+							error: "terminal session expired"
+						};
 						try {
-							ws.close(1e3);
+							ws.send(JSON.stringify(expired));
 						} catch {}
-					});
-					ws.on("message", (data) => {
-						let frame;
 						try {
-							frame = JSON.parse(String(data));
-						} catch {
-							return;
-						}
-						if (frame.type === "input") session?.send(frame.data);
-						else if (frame.type === "resize") session?.resize(Math.max(2, frame.cols), Math.max(1, frame.rows));
-						else if (frame.type === "auth_response") {
-							if (pendingAuthFinish !== void 0) {
-								const fn = pendingAuthFinish;
-								pendingAuthFinish = void 0;
-								fn(frame.responses);
-							}
-						}
-					});
-					ws.on("close", () => {
-						closed = true;
-						closeSession();
-					});
-					ws.on("error", () => {
-						closed = true;
-						closeSession();
-					});
+							ws.close(1e3);
+						} catch {}
+						return;
+					}
+					terminalSessions.open(ws, alias, size);
 				});
 			}
-		}
+		},
+		terminalSessions
 	};
 }
 //#endregion
@@ -2961,38 +3128,111 @@ function sshClusterTool(engine) {
 * the loader accepts a standalone install of the same package side by side;
 * without this guard the second instance would still re-register the same
 * webserver routes, tools, settings namespaces, and system-prompt sections
-* and fail the boot. mountOnce makes the second host apply a no-op for the
-* lifetime of the first instance (the browser half is already deduped by
-* package name in the client module host).
+* and fail the boot. mountOnce makes a mount of an already-mounted package a
+* no-op for as long as the first instance lives (the browser half is already
+* deduped by package name in the client module host).
+*
+* A no-op is only safe while the holder is ALIVE. The holder can be disposed
+* long after the refused mount ran its course: the Host reloads a profile by
+* creating the new loader entries before the old ones are torn down (a
+* plugin-manager enable/disable/install write, a settings-driven row reload,
+* HMR), so the new aggregate shell entry mounts its family plugin while the
+* previous entry still owns the name. Dropping that refused mount lost the
+* plugin for good - the previous entry then disposed its own mount, releasing
+* the name with nobody left to take it, and the family row stayed listed as
+* active while its host routes 404ed (the task-board panel showed
+* "board.hostError.notMounted", no degraded record appeared, and only a Host
+* restart recovered it).
+*
+* The refused mount is therefore QUEUED, not dropped, and replayed the moment
+* the holder releases the name - if the waiting fiber is still alive then. The
+* single-instance guarantee is unchanged: exactly one mount is live per
+* package name, and the replay re-enters the guard so a later mount still
+* dedupes against it.
 *
 * The registry rides a global symbol so two module instances of the same
-* package (npm copy vs repository link) still share one verdict. cordis
-* `ctx.effect` runs its callback immediately and treats the callback's
+* package (npm copy vs repository link) still share one verdict. That symbol
+* is a CROSS-REPOSITORY contract, not this file's private state: the four
+* satellite packages (dsh-skins / dsh-pet / dsh-presets /
+* dsh-community-plugins) are separate repositories carrying their own copy of
+* this guard, rebuilt on their own schedule, so the value under `MOUNTED`
+* must keep the shape every published copy reads (a `Set` of package names
+* with `has`/`add`/`delete`). The wait queues this guard added therefore live
+* under their own additive key, and the registry reads back a `Set` even when
+* some other build left a different value there. Changing `MOUNTED`'s shape
+* in place broke that contract once: a satellite's legacy copy created a
+* `Set`, the family's new copy read it as a `Map`, and every family row
+* mounted after it failed with "claims.get is not a function".
+*
+* cordis `ctx.effect` runs its callback immediately and treats the callback's
 * return value as the fiber disposer, so the unmarker is returned, not run.
 */
+/** Published cross-repository contract: package names currently mounted. */
 const MOUNTED = Symbol.for("dsh-web.mounted-plugins");
+/** Additive key this guard owns: refused mounts waiting for the name. */
+const WAITERS = Symbol.for("dsh-web.mounted-plugins.waiters");
+/**
+* The shared name registry, always a `Set` whatever another build stored here:
+* a foreign value (an interim shape, a hand-written global) must not take every
+* family plugin down with it.
+* @returns the process-wide set of mounted package names.
+*/
 function mountedSet() {
 	const registry = globalThis;
-	return registry[MOUNTED] ??= /* @__PURE__ */ new Set();
+	const existing = registry[MOUNTED];
+	if (existing instanceof Set) return existing;
+	const created = /* @__PURE__ */ new Set();
+	registry[MOUNTED] = created;
+	return created;
+}
+/** Queue per package name for mounts refused while a holder was alive. */
+function mountWaiters() {
+	const registry = globalThis;
+	return registry[WAITERS] ??= /* @__PURE__ */ new Map();
 }
 /**
 * Wrap a cordis plugin apply so the package runs at most once per process.
-* The first mount registers normally and unmarks when its fiber disposes;
-* any later mount of the same package name is a no-op.
+* The first mount registers normally and releases the name when its fiber
+* disposes; a mount refused while that name is held waits for the release and
+* then runs, unless its own fiber disposes first.
 * @param packageName - npm package identity shared by every install source.
 * @param fn - the original plugin apply.
 * @returns an apply of the same shape.
 */
 function mountOnce(packageName, fn) {
-	return ((...args) => {
+	const mount = (...args) => {
 		const mounted = mountedSet();
-		if (mounted.has(packageName)) return;
+		const ctx = args[0];
+		if (mounted.has(packageName)) {
+			const waiters = mountWaiters();
+			const queue = waiters.get(packageName) ?? [];
+			let alive = true;
+			const pending = { run: () => {
+				if (alive) mount(...args);
+			} };
+			ctx?.effect?.(() => () => {
+				alive = false;
+				const index = queue.indexOf(pending);
+				if (index >= 0) queue.splice(index, 1);
+			});
+			queue.push(pending);
+			waiters.set(packageName, queue);
+			return;
+		}
 		mounted.add(packageName);
-		args[0]?.effect?.(() => () => {
+		ctx?.effect?.(() => () => {
 			mounted.delete(packageName);
+			const waiters = mountWaiters();
+			const queue = waiters.get(packageName);
+			if (queue === void 0) return;
+			waiters.delete(packageName);
+			for (const waiter of queue.splice(0)) queueMicrotask(() => {
+				waiter.run();
+			});
 		});
 		return fn(...args);
-	});
+	};
+	return mount;
 }
 //#endregion
 //#region src/index.ts
@@ -3059,7 +3299,7 @@ function applyImpl(ctx, config) {
 			enabled
 		};
 	};
-	const { routes, upgrade } = makeRoutes({
+	const { routes, upgrade, terminalSessions } = makeRoutes({
 		store,
 		engine
 	});
@@ -3100,6 +3340,7 @@ function applyImpl(ctx, config) {
 			return () => {
 				for (const dispose of disposers) dispose();
 				upgradeDisposer();
+				terminalSessions.dispose();
 			};
 		}, "dsh-ssh: routes");
 		disposeTools = ctx.effect(() => {