Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(switchdash): attach remote terminals on demand, not on provision

amaudruz10227198887c
diff --git a/dash/apps/switchdash-desktop/src/main/core/agent-runtime/attachment/types.ts b/dash/apps/switchdash-desktop/src/main/core/agent-runtime/attachment/types.ts
index a0fb26c06..7d1ab3f57 100644
--- a/dash/apps/switchdash-desktop/src/main/core/agent-runtime/attachment/types.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/agent-runtime/attachment/types.ts
@@ -39,3 +39,19 @@ export interface AttachableRuntime {
isAttached(): boolean;
}
+
+/**
+ * Whether a runtime participates in per-host attachment capping. False for
+ * local runtimes, which have no shared SSH transport to protect.
+ */
+export function isAttachableRuntime(runtime: unknown): runtime is AttachableRuntime {
+ const candidate = runtime as Partial<AttachableRuntime> | null;
+ return (
+ typeof candidate?.attachHostKey === 'string' &&
+ typeof candidate.attachSessionId === 'string' &&
+ typeof candidate.ensureAttachable === 'function' &&
+ typeof candidate.attach === 'function' &&
+ typeof candidate.detachForEviction === 'function' &&
+ typeof candidate.isAttached === 'function'
+ );
+}
diff --git a/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/ssh-agent-runtime.ts b/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/ssh-agent-runtime.ts
index 26451f362..58c6ecd43 100644
--- a/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/ssh-agent-runtime.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/ssh-agent-runtime.ts
@@ -691,7 +691,10 @@ export class SshAgentRuntime implements AgentRuntimeProvider, AttachableRuntime
private detachPty(): void {
const pty = this.supervisor.stop() ?? this.pty;
this.pty = null;
- ptySessionRegistry.unregister(this.ptySessionId);
+ // On tmux the pane outlives the PTY and a later attach lands back on it, so
+ // keep the size — otherwise the re-attach spawns at 80x24 and tmux repaints
+ // the pane that small inside a full-width terminal.
+ ptySessionRegistry.unregister(this.ptySessionId, { preserveSize: this.tmux });
if (pty) {
try {
pty.kill();
diff --git a/dash/apps/switchdash-desktop/src/main/core/agents/remote-session-reconciler.ts b/dash/apps/switchdash-desktop/src/main/core/agents/remote-session-reconciler.ts
index ce3925e5d..c90f1fc99 100644
--- a/dash/apps/switchdash-desktop/src/main/core/agents/remote-session-reconciler.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/agents/remote-session-reconciler.ts
@@ -494,6 +494,11 @@ class RemoteSessionReconciler {
agentId: agent.id,
title: roomId ? `Switch room ${roomId}` : 'Remote session',
autoApprove: agent.autoApprove,
+ // The VM is already running this session; adoption only needs the row and
+ // the sidecar relay that reports on it. A terminal is opened when the user
+ // opens the session — a first sync against a busy host would otherwise
+ // spawn one PTY per adopted session in a single pass.
+ attach: false,
});
if (!result.success) {
if (result.error.type === 'already-exists') {
diff --git a/dash/apps/switchdash-desktop/src/main/core/pty/pty-session-registry.ts b/dash/apps/switchdash-desktop/src/main/core/pty/pty-session-registry.ts
index d1783214c..17c4fcfa4 100644
--- a/dash/apps/switchdash-desktop/src/main/core/pty/pty-session-registry.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/pty/pty-session-registry.ts
@@ -103,7 +103,17 @@ export class PtySessionRegistry {
events.emit(ptyStartedChannel, { id: sessionId });
}
- unregister(sessionId: string, options: { pty?: Pty; exitInfo?: PtyExitInfo } = {}): void {
+ /**
+ * `preserveSize` keeps the last known terminal dimensions after the pty is
+ * gone. Set it when the session is expected to come back — a detached remote
+ * session re-attaches onto the same tmux pane, and without the remembered
+ * size it respawns at the 80x24 default and tmux repaints the pane at that
+ * size inside a much larger terminal.
+ */
+ unregister(
+ sessionId: string,
+ options: { pty?: Pty; exitInfo?: PtyExitInfo; preserveSize?: boolean } = {}
+ ): void {
if (options.pty !== undefined && this.ptyMap.get(sessionId) !== options.pty) return;
this.pendingFlushes.get(sessionId)?.();
if (options.exitInfo !== undefined) {
@@ -116,7 +126,7 @@ export class PtySessionRegistry {
this.ringBuffers.delete(sessionId);
this.activeConsumers.delete(sessionId);
this.metadata.delete(sessionId);
- this.lastSizes.delete(sessionId);
+ if (!options.preserveSize) this.lastSizes.delete(sessionId);
}
get(sessionId: string): Pty | undefined {
diff --git a/dash/apps/switchdash-desktop/src/main/core/sessions/controller.ts b/dash/apps/switchdash-desktop/src/main/core/sessions/controller.ts
index d9ee2ca04..97863ee6c 100644
--- a/dash/apps/switchdash-desktop/src/main/core/sessions/controller.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/sessions/controller.ts
@@ -1,3 +1,4 @@
+import { remoteAttachmentPool } from '@main/core/agent-runtime/attachment/production-remote-attachment-pool';
import type { CreateSessionParams, SessionLifecycleStatus } from '@shared/core/sessions/sessions';
import { createRPCController } from '@shared/lib/ipc/rpc';
import { generateSessionName } from './name-generation/generateSessionName';
@@ -12,6 +13,24 @@ export const sessionController = createRPCController({
hydrateSession,
dehydrateSession,
markSessionSeen,
+ /**
+ * Tell the main process which session the user is looking at.
+ *
+ * Attachment is capped per remote host, and the focused session is the one
+ * that must always have a terminal: it is pinned against eviction and
+ * attached on demand. Pass null when leaving the session view.
+ */
+ async focusSession(sessionId: string | null) {
+ remoteAttachmentPool.setFocused(sessionId);
+ },
+ /** Attach a session's terminal on request — the detached state's Attach button. */
+ async attachSession(sessionId: string) {
+ return remoteAttachmentPool.requestAttach(sessionId, 'user');
+ },
+ /** Close a session's terminal, leaving its agent running on the VM. */
+ async detachSession(sessionId: string) {
+ await remoteAttachmentPool.requestDetach(sessionId);
+ },
async createSession(params: CreateSessionParams) {
return sessionService.createSession(params);
},
diff --git a/dash/apps/switchdash-desktop/src/main/core/sessions/operations/createSession.ts b/dash/apps/switchdash-desktop/src/main/core/sessions/operations/createSession.ts
index 412eef0a5..97f6247ce 100644
--- a/dash/apps/switchdash-desktop/src/main/core/sessions/operations/createSession.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/sessions/operations/createSession.ts
@@ -1,5 +1,6 @@
import { err, ok, type Result } from '@switchdash/shared';
import { eq, sql } from 'drizzle-orm';
+import { isAttachableRuntime } from '@main/core/agent-runtime/attachment/types';
import { getAgentById } from '@main/core/agents/getAgentById';
import { locationManager } from '@main/core/locations/location-manager';
import { db } from '@main/db/client';
@@ -65,7 +66,15 @@ export async function createSession(
const built = await provisionSessionRuntime(session, location);
await sessionRuntimeManager.registerSession(session.id, built, location.ctx);
- await built.agent.start(session, params.initialSize, false, params.initialPrompt);
+ if (params.attach === false && isAttachableRuntime(built.agent)) {
+ // Adopting a session the VM already started: the agent is running in its
+ // tmux pane, so only the sidecar and its shared relay are needed. Opening
+ // a terminal for each adopted session would put a whole host's worth of
+ // channels on one transport in a single reconcile pass.
+ await built.agent.ensureAttachable(session);
+ } else {
+ await built.agent.start(session, params.initialSize, false, params.initialPrompt);
+ }
} catch (e) {
await db.delete(sessions).where(eq(sessions.id, params.id));
return err({ type: 'spawn-failed', message: e instanceof Error ? e.message : String(e) });
diff --git a/dash/apps/switchdash-desktop/src/main/core/sessions/operations/ensureSessionAttachable.ts b/dash/apps/switchdash-desktop/src/main/core/sessions/operations/ensureSessionAttachable.ts
new file mode 100644
index 000000000..da9cb3edc
--- /dev/null
+++ b/dash/apps/switchdash-desktop/src/main/core/sessions/operations/ensureSessionAttachable.ts
@@ -0,0 +1,33 @@
+import { remoteAttachmentPool } from '@main/core/agent-runtime/attachment/production-remote-attachment-pool';
+import { isAttachableRuntime } from '@main/core/agent-runtime/attachment/types';
+import { resolveSessionAgent } from '../../locations/utils';
+import { loadSessionWithAgent } from '../session-join';
+import { mapSessionRowToSession } from '../utils/utils';
+
+/**
+ * Bring a remote session fully to life *except* its terminal: the on-VM sidecar
+ * and the shared hook-event relay, so it reports status, room membership and
+ * notifications, and can be attached later without further setup.
+ *
+ * This is what a room-connected session needs at startup. The agent itself runs
+ * in a tmux pane on the VM and the sidecar injects room messages there, so a
+ * local PTY buys nothing until someone actually looks at the session.
+ *
+ * Deliberately does not write `agent_session_id`: that stays the marker for a
+ * real first spawn, in `hydrateSession`.
+ *
+ * Returns false for a local session, which has no sidecar and must be hydrated
+ * the usual way.
+ */
+export async function ensureSessionAttachable(sessionId: string): Promise<boolean> {
+ const agent = resolveSessionAgent(sessionId);
+ if (!agent) throw new Error('Session not found');
+ if (!isAttachableRuntime(agent)) return false;
+
+ const loaded = await loadSessionWithAgent(sessionId);
+ if (!loaded) throw new Error('Session row not found');
+
+ await agent.ensureAttachable(mapSessionRowToSession(loaded.row, loaded.providerId, loaded.name));
+ remoteAttachmentPool.register(agent);
+ return true;
+}
diff --git a/dash/apps/switchdash-desktop/src/main/core/sessions/operations/hydrateSession.ts b/dash/apps/switchdash-desktop/src/main/core/sessions/operations/hydrateSession.ts
index cb9bb4f0d..4e0b8623d 100644
--- a/dash/apps/switchdash-desktop/src/main/core/sessions/operations/hydrateSession.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/sessions/operations/hydrateSession.ts
@@ -1,10 +1,21 @@
import { eq } from 'drizzle-orm';
+import { remoteAttachmentPool } from '@main/core/agent-runtime/attachment/production-remote-attachment-pool';
+import { isAttachableRuntime } from '@main/core/agent-runtime/attachment/types';
import { db } from '@main/db/client';
import { sessions } from '@main/db/schema';
import { resolveSessionAgent } from '../../locations/utils';
import { loadSessionWithAgent } from '../session-join';
import { mapSessionRowToSession } from '../utils/utils';
+/**
+ * Open a session's terminal.
+ *
+ * A first spawn has no remote pane yet and carries the session's initial
+ * prompt, so it goes straight to the runtime. Every later hydrate is a view
+ * onto a pane that is already running, and goes through the attachment pool —
+ * which bounds how many terminals a single host holds open and serialises the
+ * channel opens so a slow tunnel is not stampeded.
+ */
export async function hydrateSession(sessionId: string): Promise<void> {
const agent = resolveSessionAgent(sessionId);
if (!agent) throw new Error('Session not found');
@@ -21,12 +32,19 @@ export async function hydrateSession(sessionId: string): Promise<void> {
}
const config = row.config ?? {};
- const isResuming = !isFirstSpawn;
+ const session = mapSessionRowToSession(row, loaded.providerId, loaded.name);
+
+ if (!isFirstSpawn && isAttachableRuntime(agent)) {
+ await agent.ensureAttachable(session);
+ remoteAttachmentPool.register(agent);
+ await remoteAttachmentPool.requestAttach(sessionId, 'user');
+ return;
+ }
await agent.start(
- mapSessionRowToSession(row, loaded.providerId, loaded.name),
+ session,
undefined,
- isResuming,
+ !isFirstSpawn,
isFirstSpawn ? config.initialPrompt : undefined
);
}
diff --git a/dash/apps/switchdash-desktop/src/main/core/sessions/session-runtime-manager.ts b/dash/apps/switchdash-desktop/src/main/core/sessions/session-runtime-manager.ts
index d96eab38c..97cf85c13 100644
--- a/dash/apps/switchdash-desktop/src/main/core/sessions/session-runtime-manager.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/sessions/session-runtime-manager.ts
@@ -1,4 +1,6 @@
import { ok, type Result } from '@switchdash/shared';
+import { remoteAttachmentPool } from '@main/core/agent-runtime/attachment/production-remote-attachment-pool';
+import { isAttachableRuntime } from '@main/core/agent-runtime/attachment/types';
import type { AgentRuntimeProvider } from '@main/core/agent-runtime/types';
import type { IExecutionContext } from '@main/core/execution-context/types';
import {
@@ -53,6 +55,7 @@ class SessionRuntimeManager {
>({
postTeardown: (sessionId, stored) => {
this._sessionsByLocation.get(stored.locationId)?.delete(sessionId);
+ remoteAttachmentPool.unregister(sessionId);
},
});
private readonly _sessionsByLocation = new Map<string, Set<string>>();
@@ -78,6 +81,10 @@ class SessionRuntimeManager {
const byLocation = this._sessionsByLocation.get(result.locationId) ?? new Set<string>();
byLocation.add(sessionId);
this._sessionsByLocation.set(result.locationId, byLocation);
+
+ // Remote runtimes are attachment-capped per host; local ones have no shared
+ // transport to protect and are never pooled.
+ if (isAttachableRuntime(result.agent)) remoteAttachmentPool.register(result.agent);
}
async teardownSession(
diff --git a/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-client-proxy.ts b/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-client-proxy.ts
index 466bc1e42..8ed3089ee 100644
--- a/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-client-proxy.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-client-proxy.ts
@@ -29,10 +29,28 @@ type RemoteShellProfileState =
* servers cap simultaneous sessions (OpenSSH MaxSessions defaults to 10, and
* proxies/tunnels can be lower); bursts of parallel probes (dependency checks,
* plugin status, gh auth) otherwise trip "Channel open failure: open failed".
- * Long-lived PTY channels (execPty) are intentionally not counted here.
+ * Long-lived PTY channels (execPty) are intentionally not counted here — they
+ * would hold a slot for the terminal's whole life. They get their own
+ * open-only semaphore below.
*/
const MAX_CONCURRENT_EXEC = 4;
+/**
+ * Max PTY channel OPENS in flight at once.
+ *
+ * A pty channel is long-lived — it is the interactive terminal — so it cannot
+ * hold an exec slot for its lifetime without starving every command on the
+ * connection. But the *open* is the expensive part on a slow transport, and a
+ * burst of them is what saturates a tunnel: one host re-attaching all its
+ * sessions at once pushed opens past `CHANNEL_OPEN_TIMEOUT_MS` and tripped the
+ * wedge watchdog. The slot is held only until the server answers, then freed
+ * while the channel lives on.
+ *
+ * `RemoteAttachmentPool` already serialises attaches per host; this is the
+ * backstop for every other path that opens a pty.
+ */
+const MAX_CONCURRENT_PTY_OPENS = 2;
+
/**
* Deadline for the server to answer a channel open (exec / pty / direct-tcpip
* / sftp). Healthy opens answer in milliseconds; a silent open is the
@@ -55,6 +73,10 @@ export class SshClientProxy {
private activeExec = 0;
private readonly execQueue: Array<() => void> = [];
+ /** Semaphore state for pty channel opens (held across the open only). */
+ private activePtyOpens = 0;
+ private readonly ptyOpenQueue: Array<() => void> = [];
+
constructor(
readonly connectionId: string,
private healthReporter?: SshChannelHealthReporter
@@ -154,6 +176,26 @@ export class SshClientProxy {
}
}
+ /** Run `fn` once a pty-open slot is free; queues it when at capacity. */
+ private acquirePtyOpenSlot(fn: () => void): void {
+ if (this.activePtyOpens < MAX_CONCURRENT_PTY_OPENS) {
+ this.activePtyOpens++;
+ fn();
+ } else {
+ this.ptyOpenQueue.push(fn);
+ }
+ }
+
+ /** Free a pty-open slot and start the next queued open, if any. */
+ private releasePtyOpenSlot(): void {
+ const next = this.ptyOpenQueue.shift();
+ if (next) {
+ next();
+ } else {
+ this.activePtyOpens = Math.max(0, this.activePtyOpens - 1);
+ }
+ }
+
/**
* Guard a channel-open callback with the open deadline. Returns a wrapped
* callback; when the deadline fires first, `callback` receives an
@@ -241,22 +283,39 @@ export class SshClientProxy {
execPty(command: string, options: ExecOptions, callback: ClientCallback): void {
// The timeout guards only the channel OPEN; the pty channel itself is
- // long-lived (it is the interactive terminal).
- const attempt = (retrying: boolean): void => {
- this.client.exec(
- command,
- options,
- this.withChannelOpenTimeout('pty', (err, channel) => {
- if (err && !retrying && this.recoverFromAgentForwardRefusal(err)) {
- attempt(true);
- return;
- }
- callback(err, channel);
- })
- );
- };
+ // long-lived (it is the interactive terminal). The slot is likewise held
+ // only across the open, so terminals never starve each other once running.
+ this.acquirePtyOpenSlot(() => {
+ let released = false;
+ const release = () => {
+ if (released) return;
+ released = true;
+ this.releasePtyOpenSlot();
+ };
+
+ const attempt = (retrying: boolean): void => {
+ try {
+ this.client.exec(
+ command,
+ options,
+ this.withChannelOpenTimeout('pty', (err, channel) => {
+ if (err && !retrying && this.recoverFromAgentForwardRefusal(err)) {
+ attempt(true);
+ return;
+ }
+ release();
+ callback(err, channel);
+ })
+ );
+ } catch (err) {
+ // e.g. connection not available — surface it, don't leak the slot.
+ release();
+ callback(err as Error, undefined as never);
+ }
+ };
- attempt(false);
+ attempt(false);
+ });
}
/**
@@ -314,6 +373,13 @@ export class SshClientProxy {
this.activeExec++;
fn();
}
+
+ const queuedPtyOpens = this.ptyOpenQueue.splice(0);
+ this.activePtyOpens = 0;
+ for (const fn of queuedPtyOpens) {
+ this.activePtyOpens++;
+ fn();
+ }
}
/**
diff --git a/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-connection-manager.ts b/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-connection-manager.ts
index 434cc52a1..ea4ec1997 100644
--- a/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-connection-manager.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/ssh/lifecycle/ssh-connection-manager.ts
@@ -310,6 +310,16 @@ export class SshConnectionManager extends EventEmitter {
this.emitHealthChanged(connectionId, record.health);
}
+ // Record what actually failed. Only the wedge itself used to be logged,
+ // which left "3 failures" with no way to tell an exhausted MaxSessions from
+ // a saturated tunnel from a genuinely dead transport.
+ this.deps.log.warn('SshConnectionManager: channel open failed', {
+ connectionId,
+ failures: record.channelFailureStreak,
+ state: record.state,
+ error: error instanceof Error ? error.message : String(error),
+ });
+
if (
record.channelFailureStreak >= WEDGE_FAILURE_THRESHOLD &&
record.state === 'connected' &&
@@ -317,7 +327,12 @@ export class SshConnectionManager extends EventEmitter {
) {
this.deps.log.error(
'SshConnectionManager: connection wedged (consecutive channel failures) — forcing rebuild',
- { connectionId, failures: record.channelFailureStreak }
+ {
+ event: 'ssh_wedge_rebuild',
+ connectionId,
+ failures: record.channelFailureStreak,
+ lastError: error instanceof Error ? error.message : String(error),
+ }
);
record.channelFailureStreak = 0;
// Destroying the client fires its close handler, which invalidates the
diff --git a/dash/apps/switchdash-desktop/src/main/core/switch-rooms/restore-sessions.ts b/dash/apps/switchdash-desktop/src/main/core/switch-rooms/restore-sessions.ts
index 9d0fed5b2..ccca26378 100644
--- a/dash/apps/switchdash-desktop/src/main/core/switch-rooms/restore-sessions.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/switch-rooms/restore-sessions.ts
@@ -1,5 +1,6 @@
import { locationManager } from '@main/core/locations/location-manager';
import { getLocationById } from '@main/core/locations/store';
+import { ensureSessionAttachable } from '@main/core/sessions/operations/ensureSessionAttachable';
import { hydrateSession } from '@main/core/sessions/operations/hydrateSession';
import { loadSessionWithAgent } from '@main/core/sessions/session-join';
import { sessionService } from '@main/core/sessions/session-service';
@@ -7,16 +8,23 @@ import { log } from '@main/lib/logger';
import { switchRoomService } from './switch-room-service';
/**
- * Launch every session that was connected to a Switch room before the last
+ * Bring back every session that was connected to a Switch room before the last
* shutdown, so it receives and responds to room events without the user opening
- * its terminal. Replays the renderer's open sequence from the main process:
- * open the location → provision the session runtime → hydrate the session
- * (which spawns the PTY and, via the session-launch path, restarts the room
- * poller). Sessions whose row or location no longer exist are pruned.
+ * its terminal. Sessions whose row or location no longer exist are pruned.
*
- * This deliberately spawns the agent process for each room-connected session at
- * startup — keystroke injection requires a live TUI, so there is no lighter way
- * to deliver room messages to an unopened session.
+ * How far to go depends on where the session runs:
+ *
+ * - **Local**: the agent process is this app's to run, and keystroke injection
+ * requires a live TUI, so the session is hydrated — PTY and all.
+ * - **Remote**: the agent lives in a tmux pane on the VM and the on-VM sidecar's
+ * watcher starts it and injects room messages there (`TmuxInjectionSink`), all
+ * without this app. Only the sidecar and its shared hook-event relay are
+ * ensured, which is what feeds status, room membership and notifications back.
+ * No PTY is opened: it would be a terminal nobody is looking at, holding a
+ * channel on a transport every other session on that host shares. One host
+ * with 51 such sessions saturated its tunnel badly enough to wedge the
+ * connection in a loop. The terminal is opened on demand when the session is
+ * actually viewed.
*/
export async function restoreSwitchRoomSessions(): Promise<void> {
const sessionIds = await switchRoomService.listPersistedSessionIds();
@@ -24,6 +32,7 @@ export async function restoreSwitchRoomSessions(): Promise<void> {
const stale: string[] = [];
let launched = 0;
+ let attachable = 0;
let orphaned = 0;
for (const sessionId of sessionIds) {
@@ -69,8 +78,12 @@ export async function restoreSwitchRoomSessions(): Promise<void> {
}
await sessionService.provisionSession(sessionId);
- await hydrateSession(sessionId);
- launched += 1;
+ if (await ensureSessionAttachable(sessionId)) {
+ attachable += 1;
+ } else {
+ await hydrateSession(sessionId);
+ launched += 1;
+ }
} catch (error) {
log.warn('restoreSwitchRoomSessions: failed to launch room-connected session', {
sessionId,
@@ -81,8 +94,11 @@ export async function restoreSwitchRoomSessions(): Promise<void> {
if (stale.length > 0) await switchRoomService.prunePersisted(stale);
- log.info('restoreSwitchRoomSessions: launched room-connected sessions at startup', {
+ log.info('restoreSwitchRoomSessions: restored room-connected sessions at startup', {
+ // `launched` spawned an agent locally; `attachable` only ensured the remote
+ // sidecar + relay, leaving the terminal to be opened on demand.
launched,
+ attachable,
pruned: stale.length,
orphaned,
});
diff --git a/dash/apps/switchdash-desktop/src/shared/core/sessions/sessions.ts b/dash/apps/switchdash-desktop/src/shared/core/sessions/sessions.ts
index a441e8fa1..e0098edba 100644
--- a/dash/apps/switchdash-desktop/src/shared/core/sessions/sessions.ts
+++ b/dash/apps/switchdash-desktop/src/shared/core/sessions/sessions.ts
@@ -75,6 +75,15 @@ export type CreateSessionParams = {
* the parent `agentId` (it runs in the parent's working directory).
*/
agentName?: string;
+ /**
+ * Open a terminal for the new session. Defaults to true.
+ *
+ * Pass false when the agent is already running and the row is only catching
+ * up with it — the remote session reconciler adopting a session the VM
+ * started on its own. Such a session is made attachable (sidecar + hook-event
+ * relay) but gets no PTY until someone views it.
+ */
+ attach?: boolean;
};
export type CreateSessionError =