Skip to content

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

fix(switchdash): report a stopped managed stack, not a gateway timeout

amaudruz95680fdf1318
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.test.ts b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.test.ts
index b1ea051b7..ae34da0f3 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.test.ts
@@ -15,7 +15,7 @@ vi.mock('@main/core/remote-hosts/production-host-reachability', () => ({
hostReachabilityService: { isBlocked: isHostBlockedMock, get: getReachability },
}));
-const { isManagedServerRunning, managedServerHostBlocked } =
+const { isManagedServerRunning, managedServerHostBlocked, managedServerStoppedPhase } =
await import('./managed-server-status');
function reachability(overrides: Record<string, unknown>) {
@@ -157,3 +157,49 @@ describe('managedServerHostBlocked', () => {
expect(getReachability).not.toHaveBeenCalled();
});
});
+
+describe('managedServerStoppedPhase', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ isHostBlockedMock.mockReturnValue(false);
+ });
+
+ it('reports a stopped local stack', () => {
+ getLocalStatus.mockReturnValue({ phase: 'stopped' });
+ expect(managedServerStoppedPhase(server({ managementKind: 'local' }))).toBe('stopped');
+ });
+
+ it('reports a stack that failed to start', () => {
+ getLocalStatus.mockReturnValue({ phase: 'error' });
+ expect(managedServerStoppedPhase(server({ managementKind: 'local' }))).toBe('error');
+ });
+
+ it('lets the transitions through, so the boot sequence can reach the stack it is starting', () => {
+ for (const phase of ['starting', 'running', 'stopping']) {
+ getLocalStatus.mockReturnValue({ phase });
+ expect(managedServerStoppedPhase(server({ managementKind: 'local' }))).toBeNull();
+ }
+ });
+
+ it('returns null for an external server without probing any service', () => {
+ expect(managedServerStoppedPhase(server({ managed: false }))).toBeNull();
+ expect(getLocalStatus).not.toHaveBeenCalled();
+ expect(getRemoteStatus).not.toHaveBeenCalled();
+ });
+
+ it('reads the per-host status for a remote-managed server', () => {
+ getRemoteStatus.mockReturnValue({ phase: 'stopped' });
+ expect(managedServerStoppedPhase(server({ managementKind: 'remote', sshHost: 'host-a' }))).toBe(
+ 'stopped'
+ );
+ expect(getRemoteStatus).toHaveBeenCalledWith('host-a');
+ });
+
+ it('defers to the host state when the host is blocked, rather than reading a stale phase', () => {
+ isHostBlockedMock.mockReturnValue(true);
+ expect(
+ managedServerStoppedPhase(server({ managementKind: 'remote', sshHost: 'host-a' }))
+ ).toBeNull();
+ expect(getRemoteStatus).not.toHaveBeenCalled();
+ });
+});
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.ts b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.ts
index 6ebe3d3e7..4c4fe42de 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/managed-server-status.ts
@@ -1,4 +1,5 @@
import { hostReachabilityService } from '@main/core/remote-hosts/production-host-reachability';
+import type { LocalServerPhase } from '@shared/core/managed-switch-server/managed-switch-server';
import { type HostReachability, isHostBlocked } from '@shared/core/remote-hosts/reachability';
import type { SwitchServer } from '@shared/core/switch-servers/switch-servers';
import { localServerService } from './local-server-service';
@@ -42,3 +43,29 @@ export function managedServerHostBlocked(server: SwitchServer): HostReachability
const reachability = hostReachabilityService.get(server.sshHost);
return isHostBlocked(reachability) ? reachability : null;
}
+
+/**
+ * The phase of a managed server's stack when it is settled on *not serving*, or
+ * null when a call to it may legitimately be attempted.
+ *
+ * Only `stopped` and `error` count. `starting` and `stopping` are transitions —
+ * the stack that is coming up is reached through exactly these calls (the boot
+ * sequence registers and signs in while the phase is still `starting`), so
+ * gating on "not running" rather than "settled not running" would block the
+ * very work that makes it running.
+ *
+ * A remote-managed server whose host is blocked returns null: that is the
+ * host's state to report, via {@link managedServerHostBlocked}, and a phase
+ * read across a dead SSH forward is stale anyway.
+ */
+export function managedServerStoppedPhase(server: SwitchServer): LocalServerPhase | null {
+ if (!server.managed) return null;
+ let phase: LocalServerPhase;
+ if (server.managementKind === 'remote') {
+ if (server.sshHost === null || hostReachabilityService.isBlocked(server.sshHost)) return null;
+ phase = remoteServerService.getStatus(server.sshHost).phase;
+ } else {
+ phase = localServerService.getStatus().phase;
+ }
+ return phase === 'stopped' || phase === 'error' ? phase : null;
+}
diff --git a/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-bridge.test.ts b/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-bridge.test.ts
index 1658ba352..38a7d28c0 100644
--- a/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-bridge.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-bridge.test.ts
@@ -5,9 +5,11 @@ const refreshSession = vi.hoisted(() => vi.fn());
const reauthenticateManagedServer = vi.hoisted(() => vi.fn());
const managedServerHostBlocked = vi.hoisted(() => vi.fn(() => null));
+const managedServerStoppedPhase = vi.hoisted(() => vi.fn(() => null));
vi.mock('@main/core/managed-switch-server/managed-server-status', () => ({
managedServerHostBlocked,
+ managedServerStoppedPhase,
}));
vi.mock('./servers-store', () => ({ getSessionCookie }));
diff --git a/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-room.test.ts b/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-room.test.ts
index c4c42468e..ff34efe95 100644
--- a/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-room.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/switch-servers/create-room.test.ts
@@ -5,9 +5,11 @@ const refreshSession = vi.hoisted(() => vi.fn());
const reauthenticateManagedServer = vi.hoisted(() => vi.fn());
const managedServerHostBlocked = vi.hoisted(() => vi.fn(() => null));
+const managedServerStoppedPhase = vi.hoisted(() => vi.fn(() => null));
vi.mock('@main/core/managed-switch-server/managed-server-status', () => ({
managedServerHostBlocked,
+ managedServerStoppedPhase,
}));
vi.mock('./servers-store', () => ({ getSessionCookie }));
diff --git a/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.test.ts b/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.test.ts
index dcf4ae85b..a25397057 100644
--- a/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.test.ts
@@ -1,4 +1,8 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+ type LocalServerPhase,
+ ManagedServerStoppedError,
+} from '@shared/core/managed-switch-server/managed-switch-server';
import {
type HostReachability,
HostUnreachableError,
@@ -10,9 +14,13 @@ const refreshSession = vi.hoisted(() => vi.fn());
const reauthenticateManagedServer = vi.hoisted(() => vi.fn());
const managedServerHostBlocked = vi.hoisted(() => vi.fn<() => HostReachability | null>(() => null));
+const managedServerStoppedPhase = vi.hoisted(() =>
+ vi.fn<() => LocalServerPhase | null>(() => null)
+);
vi.mock('@main/core/managed-switch-server/managed-server-status', () => ({
managedServerHostBlocked,
+ managedServerStoppedPhase,
}));
vi.mock('./servers-store', () => ({ getSessionCookie }));
@@ -232,6 +240,40 @@ describe('gatewayFetch host reachability gate', () => {
});
});
+describe('gatewayFetch managed-stack gate', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.stubGlobal('fetch', fetchMock);
+ });
+
+ afterEach(() => {
+ managedServerStoppedPhase.mockReturnValue(null);
+ vi.unstubAllGlobals();
+ });
+
+ it('fails with the lifecycle state, without touching the network or the session', async () => {
+ managedServerStoppedPhase.mockReturnValue('stopped');
+
+ await expect(fetchMe(MANAGED)).rejects.toBeInstanceOf(ManagedServerStoppedError);
+ expect(fetchMock).not.toHaveBeenCalled();
+ // The renewal that would otherwise warn about the same absence never runs.
+ expect(getSessionCookie).not.toHaveBeenCalled();
+ expect(refreshSession).not.toHaveBeenCalled();
+ });
+
+ it('names the server, so the failure reads as the state the user is looking at', async () => {
+ managedServerStoppedPhase.mockReturnValue('stopped');
+ await expect(fetchMe(MANAGED)).rejects.toThrow(/Local's Switch stack is not running/);
+ });
+
+ it('lets calls through while the stack is up', async () => {
+ getSessionCookie.mockResolvedValue(makeJwt(24 * 60 * 60));
+ fetchMock.mockResolvedValue(okMeResponse());
+ await fetchMe(MANAGED);
+ expect(fetchMock).toHaveBeenCalledOnce();
+ });
+});
+
function jsonResponse(body: unknown): Response {
return {
status: 200,
diff --git a/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.ts b/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.ts
index 1b843ab22..277448116 100644
--- a/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/switch-servers/gateway-client.ts
@@ -1,5 +1,9 @@
import type { KnownAgentType } from '@main/core/agents/known-agent-type';
-import { managedServerHostBlocked } from '@main/core/managed-switch-server/managed-server-status';
+import {
+ managedServerHostBlocked,
+ managedServerStoppedPhase,
+} from '@main/core/managed-switch-server/managed-server-status';
+import { ManagedServerStoppedError } from '@shared/core/managed-switch-server/managed-switch-server';
import { HostUnreachableError } from '@shared/core/remote-hosts/reachability';
import type {
AddressingPolicy,
@@ -148,6 +152,14 @@ async function gatewayFetch(
const blocked = managedServerHostBlocked(server);
if (blocked) throw new HostUnreachableError(blocked);
+ // Same argument one level down: a managed stack that is stopped has no
+ // gateway listening, so every call to it can only time out and report a port
+ // that was never the problem — and the session renewal on the way there
+ // warns about the same absence a second time. Report the lifecycle state the
+ // user is already looking at instead.
+ const stopped = managedServerStoppedPhase(server);
+ if (stopped) throw new ManagedServerStoppedError(server, stopped);
+
const sendOnce = async (cookie: string | null): Promise<Response> => {
const headers: Record<string, string> = { Accept: 'application/json' };
if (options.body !== undefined) {
diff --git a/dash/apps/switchdash-desktop/src/main/lib/rpc-logging.ts b/dash/apps/switchdash-desktop/src/main/lib/rpc-logging.ts
index 677601b7e..769ccba05 100644
--- a/dash/apps/switchdash-desktop/src/main/lib/rpc-logging.ts
+++ b/dash/apps/switchdash-desktop/src/main/lib/rpc-logging.ts
@@ -1,3 +1,4 @@
+import { ManagedServerStoppedError } from '@shared/core/managed-switch-server/managed-switch-server';
import { HostUnreachableError } from '@shared/core/remote-hosts/reachability';
import type { RPCInvocationWrapper } from '@shared/lib/ipc/rpc';
import { serializeLogValue, type LogContext } from '@shared/logger';
@@ -47,11 +48,14 @@ export const withRPCLogContext: RPCInvocationWrapper = (channel, args, invoke) =
});
function logRPCFailure(channel: string, error: unknown) {
- // An unreachable host is a modeled, displayed state, not a fault of the call:
- // every view scoped to that host refuses in the same way, so logging each one
- // as an error buries real failures under a repeating wall of the same fact.
- // The host's own transition to `unreachable` is logged once, where it belongs.
- const level = error instanceof HostUnreachableError ? 'debug' : 'error';
+ // An unreachable host — or a managed stack the user has stopped — is a
+ // modeled, displayed state, not a fault of the call: every view scoped to it
+ // refuses in the same way, so logging each one as an error buries real
+ // failures under a repeating wall of the same fact. The state's own
+ // transition is logged once, where it belongs.
+ const modeled =
+ error instanceof HostUnreachableError || error instanceof ManagedServerStoppedError;
+ const level = modeled ? 'debug' : 'error';
log[level]('RPC handler failed', {
event: 'rpc_failed',
component: `rpc:${channel}`,
diff --git a/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts b/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
index 65995e1a6..8633314b1 100644
--- a/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
+++ b/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
@@ -71,6 +71,36 @@ export type LocalServerStatus = {
error: string | null;
};
+/**
+ * Raised when a call is made to a switchdash-managed server whose stack is not
+ * running. The gateway only exists while the stack is up, so reaching for it
+ * from a stopped one can only produce a transport error naming a local port
+ * that was never the problem — this reports the lifecycle state instead.
+ *
+ * It lives with the model, next to the phase it carries, so anything holding an
+ * error — including the RPC logging chokepoint — can recognise it without
+ * importing the supervisors or Docker.
+ */
+export class ManagedServerStoppedError extends Error {
+ readonly serverId: string;
+ readonly phase: LocalServerPhase;
+
+ constructor(server: { id: string; name: string }, phase: LocalServerPhase) {
+ super(managedServerStoppedReason(server.name, phase));
+ this.name = 'ManagedServerStoppedError';
+ this.serverId = server.id;
+ this.phase = phase;
+ }
+}
+
+/** Human-readable one-liner for a stopped managed stack, used in errors and the UI. */
+export function managedServerStoppedReason(serverName: string, phase: LocalServerPhase): string {
+ if (phase === 'error') {
+ return `${serverName}'s Switch stack failed to start, so its gateway is not running. Fix the error on the server's page, then start it again.`;
+ }
+ return `${serverName}'s Switch stack is not running. Start it from the server's page, then retry.`;
+}
+
/** Outcome of a start request. `docker-unavailable` and `version-downgrade` are
* separated from generic errors so the UI can point the user at installing /
* starting Docker, or explain why an older build refuses to take over a stack
diff --git a/dash/packages/switch-agent-runtime/package.json b/dash/packages/switch-agent-runtime/package.json
index 25fa31200..a4663937f 100644
--- a/dash/packages/switch-agent-runtime/package.json
+++ b/dash/packages/switch-agent-runtime/package.json
@@ -1,6 +1,6 @@
{
"name": "@sandbox-quantum/switch-agent-runtime",
- "version": "0.1.5",
+ "version": "0.1.6",
"description": "Switch agent protocol client, and the local MCP runtime built on it",
"license": "Apache-2.0",
"author": {
diff --git a/dash/packages/switch-agent-runtime/src/event-stream.ts b/dash/packages/switch-agent-runtime/src/event-stream.ts
index 55c65fe9d..16a3c33f7 100644
--- a/dash/packages/switch-agent-runtime/src/event-stream.ts
+++ b/dash/packages/switch-agent-runtime/src/event-stream.ts
@@ -170,9 +170,22 @@ export class SwitchEventStream {
});
}
+ /**
+ * Reopen the stream until it comes back, reporting on a curve.
+ *
+ * The reconnect itself is unconditional — an endpoint that is down now may be
+ * up in a moment, and this loop is the only thing that would notice. What is
+ * rationed is the reporting: an endpoint that is simply gone (a managed
+ * stack the user stopped, one session per room, each retrying forever) writes
+ * the same line every thirty seconds until the app is quit, which is how a
+ * real failure elsewhere gets lost. The first failure is reported, then
+ * powers of two, and recovery is stated so the outage has an end in the log
+ * as well as a beginning — the same discipline the heartbeat already applies.
+ */
private async streamLoop(): Promise<void> {
const { creds, connectionId, scope, filter, log, signal } = this.deps;
let backoff = INITIAL_BACKOFF_MS;
+ let failures = 0;
while (!signal.aborted) {
const socketAbort = new AbortController();
@@ -201,6 +214,13 @@ export class SwitchEventStream {
}
backoff = INITIAL_BACKOFF_MS;
+ if (failures > 0) {
+ log.warn('SwitchEventStream: stream recovered', {
+ event: 'switch_stream_recovered',
+ afterFailures: failures,
+ });
+ failures = 0;
+ }
log.debug('SwitchEventStream: stream open', {
event: 'switch_stream_open',
connectionId,
@@ -216,11 +236,16 @@ export class SwitchEventStream {
if (signal.aborted) return;
// A deliberate reopen (repoint) aborts the socket; that is not an error.
if (!socketAbort.signal.aborted) {
- log.warn('SwitchEventStream: stream error', {
- event: 'switch_stream_error',
- error: String(error),
- backoffMs: backoff,
- });
+ failures += 1;
+ if ((failures & (failures - 1)) === 0) {
+ log.warn('SwitchEventStream: stream error', {
+ event: 'switch_stream_error',
+ endpoint: creds.apiEndpoint,
+ failures,
+ error: String(error),
+ backoffMs: backoff,
+ });
+ }
await new Promise((r) => setTimeout(r, backoff));
backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
}