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(console): the automatic move repairs controllers, backs off, and shows its state in Settings (#700)

Louis Amaudruza0dba918e3ed
diff --git a/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.test.ts b/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.test.ts
index 0df85a2b5..775d2fe26 100644
--- a/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.test.ts
@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
import type { AgentMigrationEvent } from '@shared/core/agent-migration/agent-migration';
import {
type AgentMigrationDeps,
+ type MachineHealth,
AgentMigrationService,
MigrationBlockedError,
type MigrationAgent,
@@ -72,6 +73,8 @@ type World = {
clock: number;
/** The lookup for one agent; `lookup` for every agent when unset. */
lookupFor: ((agent: MigrationAgent) => TargetLookup) | null;
+ /** What repairing a machine finds; when unset, `not-set-up` while the lookup offers to set it up. */
+ heal: ((agent: MigrationAgent) => Promise<MachineHealth>) | null;
};
let world: World;
@@ -93,6 +96,12 @@ function deps(): AgentMigrationDeps {
if (world.enableFails) throw new Error('ssh: connect to host gpu-1: Connection refused');
world.lookup = world.lookupAfterEnable ?? world.lookup;
},
+ heal: async (agent) => {
+ if (world.heal) return world.heal(agent);
+ return world.lookup.canEnable && !world.lookup.target
+ ? { kind: 'not-set-up' }
+ : { kind: 'unchanged' };
+ },
},
management: {
eligibility: async () => world.eligibility,
@@ -100,6 +109,9 @@ function deps(): AgentMigrationDeps {
world.calls.push(`adopt ${switchAgentId} ${body.desired_state} on ${body.controller_id}`);
if (world.failAdoptOn === switchAgentId) throw new Error('controller_offline');
},
+ place: async (_workspaceId, switchAgentId, controllerId) => {
+ world.calls.push(`place ${switchAgentId} on ${controllerId}`);
+ },
setDesiredState: async (_workspaceId, switchAgentId, desiredState) => {
world.calls.push(`desired ${switchAgentId} ${desiredState}`);
if (world.failDesiredState) throw new Error('provider_not_installed');
@@ -194,6 +206,9 @@ function deps(): AgentMigrationDeps {
controllerStopWaitMs: 8_000,
machineReadyWaitMs: 5_000,
unmanageableRecheckMs: 60_000,
+ minRetryMs: 1_000,
+ maxRetryMs: 8_000,
+ healIntervalMs: 5_000,
};
}
@@ -224,6 +239,7 @@ beforeEach(() => {
managedView: { controllerId: CONTROLLER, desiredState: 'running' },
clock: 0,
lookupFor: null,
+ heal: null,
};
});
@@ -755,6 +771,7 @@ describe('moving every agent automatically', () => {
]);
world.enableFails = false;
world.lookupAfterEnable = ready;
+ world.clock += 1_000;
await migration.migrateEverything();
expect(migration.migrationProblems()).toEqual([]);
});
@@ -769,6 +786,118 @@ describe('moving every agent automatically', () => {
expect(adopted()).toEqual(['switch-1', 'switch-2', 'switch-3']);
});
+ it('enrolls a machine again after a revocation, and places the agents moved onto it there', async () => {
+ const migration = service();
+ await migration.migrateEverything();
+ for (const record of world.records.values())
+ world.records.set(record.agentId, { ...record, controllerId: 'revoked-controller' });
+ world.calls = [];
+ world.heal = async () => ({ kind: 'changed' });
+ world.clock += 5_000;
+ await migration.migrateEverything();
+ expect(world.calls.filter((call) => call.startsWith('place'))).toEqual([
+ `place switch-1 on ${CONTROLLER}`,
+ `place switch-2 on ${CONTROLLER}`,
+ `place switch-3 on ${CONTROLLER}`,
+ ]);
+ expect([...world.records.values()].every((record) => record.controllerId === CONTROLLER)).toBe(
+ true
+ );
+ expect(adopted()).toEqual([]);
+ });
+
+ it('waits for a repaired controller to reach Switch before placing agents on it', async () => {
+ const ready = world.lookup;
+ world.lookup = { ...ready, target: null, blocker: 'Not reached Switch yet.' };
+ world.heal = async () => ({ kind: 'changed' });
+ const migration = service({
+ sleep: async (ms) => {
+ world.clock += ms;
+ world.lookup = ready;
+ },
+ });
+ await migration.migrateEverything();
+ expect(adopted()).toHaveLength(3);
+ });
+
+ it('leaves the agents of a server that cannot take the controller alone, saying why on the overview', async () => {
+ world.heal = async (agent) =>
+ agent.serverId === 'server-2'
+ ? { kind: 'incompatible', reason: 'Local dev accepts agents controller protocol 1-1.' }
+ : { kind: 'unchanged' };
+ const migration = service();
+ await migration.migrateEverything();
+ expect(adopted()).toEqual(['switch-1', 'switch-2']);
+ expect(migration.migrationProblems()).toEqual([]);
+ const overview = await migration.overview();
+ expect(
+ overview.machines.map((m) => [m.machine, m.serverId, m.moved, m.total, m.controller?.kind])
+ ).toEqual([
+ ['this computer', 'server-1', 1, 1, 'ready'],
+ ['gpu-1', 'server-1', 1, 1, 'ready'],
+ ['gpu-1', 'server-2', 0, 1, 'incompatible'],
+ ]);
+ });
+
+ it('reports a machine that cannot be repaired on each of its agents', async () => {
+ world.heal = async (agent) => {
+ if (agent.sshHost)
+ throw new Error('Console cannot tell whether gpu-1’s controller runs: ssh: timed out');
+ return { kind: 'unchanged' };
+ };
+ const migration = service();
+ await migration.migrateEverything();
+ expect(adopted()).toEqual(['switch-1']);
+ expect(migration.migrationProblems().map((p) => [p.name, p.message])).toEqual([
+ ['trainer', 'Console cannot tell whether gpu-1’s controller runs: ssh: timed out'],
+ ['other', 'Console cannot tell whether gpu-1’s controller runs: ssh: timed out'],
+ ]);
+ expect((await migration.overview()).machines[1]?.controller).toEqual({
+ kind: 'failed',
+ reason: 'Console cannot tell whether gpu-1’s controller runs: ssh: timed out',
+ });
+ });
+
+ it('tries a failing agent again after a delay that doubles, up to the limit', async () => {
+ all = [PARENT];
+ world.failAdoptOn = 'switch-1';
+ const migration = service();
+ const tries = () => adopted().length;
+ await migration.migrateEverything();
+ expect(tries()).toBe(1);
+ await migration.migrateEverything();
+ expect(tries()).toBe(1);
+ world.clock += 1_000;
+ await migration.migrateEverything();
+ expect(tries()).toBe(2);
+ world.clock += 1_000;
+ await migration.migrateEverything();
+ expect(tries()).toBe(2);
+ world.clock += 1_000;
+ await migration.migrateEverything();
+ expect(tries()).toBe(3);
+ migration.recheck(PARENT.id);
+ await migration.migrateEverything();
+ expect(tries()).toBe(4);
+ });
+
+ it('counts what it left alone and what it could not ask about', async () => {
+ const base = deps().management;
+ const migration = service({
+ management: {
+ ...base,
+ eligibility: async (_workspaceId, switchAgentId) => {
+ if (switchAgentId === 'switch-2') throw new Error('Agent not found');
+ if (switchAgentId === 'switch-3')
+ return { management: true, owner: 'Grace', ownedByMe: false };
+ return base.eligibility(_workspaceId, switchAgentId);
+ },
+ },
+ });
+ await migration.migrateEverything();
+ expect(await migration.overview()).toMatchObject({ leftAlone: 1, unasked: 1, running: false });
+ });
+
it('runs one pass at a time', async () => {
const migration = service();
await Promise.all([migration.migrateEverything(), migration.migrateEverything()]);
diff --git a/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.ts b/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.ts
index ab7f0f75a..b8d7277f7 100644
--- a/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.ts
+++ b/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration-service.ts
@@ -4,6 +4,9 @@ import type {
AgentRunner,
ManagedActual,
ManagedMachine,
+ MigrationControllerState,
+ MigrationMachine,
+ MigrationOverview,
MigrationProblem,
MigrationOperation,
MigrationStage,
@@ -56,6 +59,15 @@ export type ManagedView = {
actual: ManagedActual | null;
};
+/** What repairing a machine's controller found, or did. */
+export type MachineHealth =
+ | { kind: 'not-set-up' }
+ /** It runs a usable controller, as it did. */
+ | { kind: 'unchanged' }
+ /** It was enrolled again or restarted: the controller takes a moment to reach Switch. */
+ | { kind: 'changed' }
+ | { kind: 'incompatible'; reason: string };
+
/** Switch's agent management, through the signed-in session of the agent's workspace. */
export interface MigrationManagementPort {
/** Whether the server runs agent management, and whether the signed-in user owns the agent. */
@@ -79,6 +91,8 @@ export interface MigrationManagementPort {
switchAgentId: string,
desiredState: 'running' | 'stopped'
): Promise<void>;
+ /** `PATCH …/agents/{id}` with only `controller_id`: places the agent on another controller. */
+ place(workspaceId: string, switchAgentId: string, controllerId: string): Promise<void>;
/** `DELETE …/agents/{id}`: stops managing it. `already_gone` when it was not managed. */
release(workspaceId: string, switchAgentId: string): Promise<'released' | 'already_gone'>;
/** The managed agent as the server reports it, or null when it is not managed. */
@@ -143,6 +157,14 @@ export type AgentMigrationDeps = {
* controller, or an SSH host's), as its own toggle does.
*/
enable(agent: MigrationAgent): Promise<void>;
+ /**
+ * Repairs the controller the agent's machine runs for its server: enrolls
+ * the machine again when Switch revoked or forgot it, and restarts it when
+ * it is stopped or runs an older build than this Console. `not-set-up`
+ * when the machine runs none; `incompatible` when the server cannot take
+ * this Console's controller at all.
+ */
+ heal(agent: MigrationAgent): Promise<MachineHealth>;
};
management: MigrationManagementPort;
machine: MigrationMachinePort;
@@ -160,6 +182,12 @@ export type AgentMigrationDeps = {
machineReadyWaitMs: number;
/** How long an agent found someone else's, or on a server without agent management, is not asked about again. */
unmanageableRecheckMs: number;
+ /** The first delay before a failed agent or machine is tried again; it doubles from there. */
+ minRetryMs: number;
+ /** The longest delay before a failed agent or machine is tried again. */
+ maxRetryMs: number;
+ /** How often a machine whose agents have all moved is checked for a controller to repair. */
+ healIntervalMs: number;
};
/** A move refused before anything changed, for a reason a person can act on. */
@@ -178,6 +206,11 @@ type Moving = {
stoppedByHand: boolean;
};
+/** The machine and server an agent moves onto a controller of. */
+function groupKey(agent: MigrationAgent): string {
+ return JSON.stringify([agent.sshHost ?? '', agent.serverId ?? '']);
+}
+
/**
* Agents grouped by the controller they move onto: one per machine and server,
* this computer first, then each SSH host by name.
@@ -185,7 +218,7 @@ type Moving = {
function groupByController(agents: MigrationAgent[]): MigrationAgent[][] {
const groups = new Map<string, MigrationAgent[]>();
for (const agent of agents) {
- const key = JSON.stringify([agent.sshHost ?? '', agent.serverId ?? '']);
+ const key = groupKey(agent);
groups.set(key, [...(groups.get(key) ?? []), agent]);
}
const order = (agent: MigrationAgent) => [agent.sshHost ?? '', agent.serverId ?? ''] as const;
@@ -254,6 +287,17 @@ export class AgentMigrationService {
/** Agents found someone else's, or on a server without agent management, until when. */
private readonly unmanageableUntil = new Map<string, number>();
private migrating: Promise<void> | null = null;
+ /** The agents of each machine and server, as the last pass grouped them. */
+ private groups: MigrationAgent[][] = [];
+ private readonly controllers = new Map<
+ string,
+ { state: MigrationControllerState; checkedAt: string }
+ >();
+ private readonly leftAlone = new Set<string>();
+ private readonly unasked = new Set<string>();
+ private lastPassAt: string | null = null;
+ /** When an agent, or a machine and server, is tried again, and the delay that set it. */
+ private readonly retryAt = new Map<string, { at: number; delay: number }>();
constructor(private readonly deps: AgentMigrationDeps) {}
@@ -301,10 +345,12 @@ export class AgentMigrationService {
* Moves every agent this Console runs that can be managed: linked to a
* server with agent management, and owned by the signed-in user. A machine
* that is not running managed agents yet is set up first. Turns running are
- * cut. Agents someone else owns, or on a server without agent management,
- * are left as they are; any other reason an agent did not move is kept as a
- * problem until a later pass moves it. One pass runs at a time; a call
- * during one waits for it.
+ * cut. A machine whose controller Switch revoked or forgot is enrolled
+ * again, and the agents moved onto the old one are placed on the new one.
+ * Agents someone else owns, or on a server without agent management, are
+ * left as they are; any other reason an agent did not move is kept as a
+ * problem, and tried again after a delay that doubles up to `maxRetryMs`.
+ * One pass runs at a time; a call during one waits for it.
*/
migrateEverything(): Promise<void> {
this.migrating ??= this.migrateOnce().finally(() => {
@@ -313,28 +359,67 @@ export class AgentMigrationService {
return this.migrating;
}
+ /** Where the automatic move stands, from what the passes so far found; reads nothing remote. */
+ async overview(): Promise<MigrationOverview> {
+ const machines: MigrationMachine[] = [];
+ for (const group of this.groups) {
+ const first = group[0]!;
+ const key = groupKey(first);
+ let moved = 0;
+ for (const agent of group) if (await this.isManaged(agent)) moved++;
+ const controller = this.controllers.get(key) ?? null;
+ machines.push({
+ machine: first.sshHost ?? 'this computer',
+ sshHost: first.sshHost,
+ serverId: first.serverId!,
+ total: group.length,
+ moved,
+ controller: controller?.state ?? null,
+ checkedAt: controller?.checkedAt ?? null,
+ problems: group.flatMap((agent) => {
+ const problem = this.problems.get(agent.id);
+ return problem ? [problem] : [];
+ }),
+ });
+ }
+ return {
+ machines,
+ leftAlone: this.leftAlone.size,
+ unasked: this.unasked.size,
+ running: this.migrating !== null,
+ lastPassAt: this.lastPassAt,
+ };
+ }
+
/** Forgets that an agent could not be managed, so the next pass asks Switch again. */
recheck(agentId: string): void {
this.unmanageableUntil.delete(agentId);
+ this.retryAt.delete(agentId);
+ this.retryAt.delete(`ask:${agentId}`);
}
private async migrateOnce(): Promise<void> {
+ const now = this.deps.now();
const agents = await this.deps.agents.list();
const present = new Set(agents.map((agent) => agent.id));
for (const agentId of this.problems.keys())
if (!present.has(agentId)) this.problems.delete(agentId);
const candidates: MigrationAgent[] = [];
for (const agent of agents) {
- if (
- !agent.switchAgentId ||
- !agent.workspaceId ||
- !agent.serverId ||
- (await this.isManaged(agent))
- ) {
+ if (!agent.switchAgentId || !agent.workspaceId || !agent.serverId) {
this.problems.delete(agent.id);
+ this.leftAlone.delete(agent.id);
+ this.unasked.delete(agent.id);
continue;
}
- if ((this.unmanageableUntil.get(agent.id) ?? 0) > this.deps.now()) continue;
+ if (await this.isManaged(agent)) {
+ this.leftAlone.delete(agent.id);
+ this.unasked.delete(agent.id);
+ candidates.push(agent);
+ continue;
+ }
+ if ((this.unmanageableUntil.get(agent.id) ?? 0) > now) continue;
+ if (!this.due(`ask:${agent.id}`, now)) continue;
let eligibility: Awaited<ReturnType<MigrationManagementPort['eligibility']>>;
try {
eligibility = await this.deps.management.eligibility(
@@ -346,38 +431,167 @@ export class AgentMigrationService {
agentId: agent.id,
error: message(error),
});
+ this.backOff(`ask:${agent.id}`, now);
+ this.unasked.add(agent.id);
continue;
}
+ this.unasked.delete(agent.id);
+ this.retryAt.delete(`ask:${agent.id}`);
if (!eligibility.management || !eligibility.ownedByMe) {
- this.unmanageableUntil.set(agent.id, this.deps.now() + this.deps.unmanageableRecheckMs);
+ this.unmanageableUntil.set(agent.id, now + this.deps.unmanageableRecheckMs);
this.problems.delete(agent.id);
+ this.leftAlone.add(agent.id);
continue;
}
+ this.leftAlone.delete(agent.id);
candidates.push(agent);
}
- for (const group of groupByController(candidates)) {
- const setUp = await this.setUpMachine(group);
- for (const agent of group) {
- if (setUp) {
- this.problem(agent, setUp);
- continue;
- }
- try {
+ for (const agentId of [...this.leftAlone, ...this.unasked])
+ if (!present.has(agentId)) {
+ this.leftAlone.delete(agentId);
+ this.unasked.delete(agentId);
+ }
+ this.groups = groupByController(candidates);
+ for (const group of this.groups) await this.migrateGroup(group, now);
+ this.lastPassAt = new Date(this.deps.now()).toISOString();
+ }
+
+ private controllerState(key: string, state: MigrationControllerState): void {
+ this.controllers.set(key, { state, checkedAt: new Date(this.deps.now()).toISOString() });
+ }
+
+ /**
+ * One controller's agents: makes sure the machine runs a controller this
+ * Console can place agents on (setting it up, enrolling it again after a
+ * revocation, or restarting it on this build), places the moved agents
+ * whose controller is gone on the new one, and moves the rest.
+ */
+ private async migrateGroup(group: MigrationAgent[], now: number): Promise<void> {
+ const first = group[0]!;
+ const where = first.sshHost ?? 'this computer';
+ const key = groupKey(first);
+ const managed = new Map<string, ManagedAgentRecord>();
+ for (const agent of group) {
+ const record = await this.deps.store.forIdentity(agent.id, agent.switchAgentId);
+ if (record) managed.set(agent.id, record);
+ }
+ if (!this.due(key, now)) return;
+ const waiting = group.filter((agent) => !managed.has(agent.id));
+ let controllerId: string;
+ try {
+ const prepared = await this.prepareMachine(first, where);
+ if (prepared.kind === 'incompatible') {
+ this.deps.log.warn('Not moving agents: the server cannot take this Console’s controller', {
+ machine: where,
+ serverId: first.serverId,
+ reason: prepared.reason,
+ });
+ this.backOff(key, now, this.deps.unmanageableRecheckMs);
+ this.controllerState(key, prepared);
+ for (const agent of group) this.problems.delete(agent.id);
+ return;
+ }
+ controllerId = prepared.controllerId;
+ this.retryAt.delete(key);
+ this.controllerState(key, { kind: 'ready' });
+ } catch (error) {
+ this.backOff(key, now);
+ this.controllerState(key, { kind: 'failed', reason: message(error) });
+ for (const agent of group) this.problem(agent, message(error));
+ return;
+ }
+ if (waiting.length === 0) this.backOff(key, now, this.deps.healIntervalMs);
+ for (const agent of group) {
+ const record = managed.get(agent.id);
+ if (!record && !this.due(agent.id, now)) continue;
+ try {
+ if (record) {
+ if (record.controllerId !== controllerId) await this.replace(agent, record, controllerId);
+ } else {
const state = await this.state(agent.id);
if (state.runner === 'console') {
- if (state.blocker) {
- this.problem(agent, state.blocker);
- continue;
- }
+ if (state.blocker) throw new MigrationBlockedError(state.blocker);
await this.moveToManaged(agent.id);
this.deps.log.info('Moved an agent to managed', { agentId: agent.id });
}
- this.problems.delete(agent.id);
- } catch (error) {
- this.problem(agent, message(error));
}
+ this.problems.delete(agent.id);
+ this.retryAt.delete(agent.id);
+ } catch (error) {
+ this.backOff(agent.id, now);
+ this.problem(agent, message(error));
+ }
+ }
+ }
+
+ /**
+ * The controller a group of agents is placed on, once the machine runs one
+ * this Console can use. Anything changed on the way (a machine set up,
+ * enrolled again, or restarted) is waited for until Switch lists the
+ * controller online.
+ */
+ private async prepareMachine(
+ agent: MigrationAgent,
+ where: string
+ ): Promise<{ kind: 'ready'; controllerId: string } | { kind: 'incompatible'; reason: string }> {
+ const healed = await this.deps.targets.heal(agent);
+ if (healed.kind === 'incompatible') return healed;
+ if (healed.kind === 'not-set-up') {
+ this.deps.log.info('Setting a machine up to move its agents', { machine: where });
+ try {
+ await this.deps.targets.enable(agent);
+ } catch (error) {
+ throw new Error(`${where} could not be set up to run managed agents: ${message(error)}`, {
+ cause: error,
+ });
}
}
+ const deadline = this.deps.now() + this.deps.machineReadyWaitMs;
+ for (;;) {
+ const lookup = await this.deps.targets.resolve(agent).catch((error: unknown) => ({
+ target: null,
+ blocker: message(error),
+ }));
+ if (lookup.target) return { kind: 'ready', controllerId: lookup.target.controllerId };
+ if (healed.kind === 'unchanged')
+ throw new Error(lookup.blocker ?? `${where} cannot take agents.`);
+ if (this.deps.now() >= deadline)
+ throw new Error(
+ `${where} was set up to run managed agents, but is not ready for them yet: ${lookup.blocker ?? 'it has not reached Switch'}.`
+ );
+ await this.deps.sleep(this.deps.pollMs);
+ }
+ }
+
+ /** Places a moved agent whose controller is gone on the machine's controller now. */
+ private async replace(
+ agent: MigrationAgent,
+ record: ManagedAgentRecord,
+ controllerId: string
+ ): Promise<void> {
+ await this.deps.management.place(agent.workspaceId!, agent.switchAgentId!, controllerId);
+ await this.deps.store.set({ ...record, controllerId });
+ this.deps.log.info('Placed a moved agent on its machine’s new controller', {
+ agentId: agent.id,
+ from: record.controllerId,
+ to: controllerId,
+ });
+ }
+
+ /** Whether an agent or a machine is due another try. */
+ private due(key: string, now: number): boolean {
+ return (this.retryAt.get(key)?.at ?? 0) <= now;
+ }
+
+ /**
+ * Puts off the next try: by `fixedMs` when given, otherwise twice as long as
+ * the last time, from one pass up to `maxRetryMs`.
+ */
+ private backOff(key: string, now: number, fixedMs?: number): void {
+ const last = this.retryAt.get(key)?.delay ?? 0;
+ const delay =
+ fixedMs ?? Math.min(Math.max(last * 2, this.deps.minRetryMs), this.deps.maxRetryMs);
+ this.retryAt.set(key, { at: now + delay, delay });
}
private problem(agent: MigrationAgent, why: string): void {
@@ -397,40 +611,6 @@ export class AgentMigrationService {
return (await this.deps.store.forIdentity(agent.id, agent.switchAgentId)) !== null;
}
- /**
- * Sets up the machine a group of agents moves onto when one of them is
- * waiting for exactly that, and waits until it can take agents. Null when
- * there was nothing to do or it is ready; otherwise why the group cannot move.
- */
- private async setUpMachine(group: MigrationAgent[]): Promise<string | null> {
- const waiting = [];
- for (const agent of group) {
- if (await this.isManaged(agent)) continue;
- const state = await this.state(agent.id).catch(() => null);
- if (state?.runner === 'console' && state.canEnableTarget) waiting.push(agent);
- }
- const first = waiting[0];
- if (!first) return null;
- const where = first.sshHost ?? 'this computer';
- this.deps.log.info('Setting a machine up to move its agents', { machine: where });
- try {
- await this.deps.targets.enable(first);
- } catch (error) {
- return `${where} could not be set up to run managed agents: ${message(error)}`;
- }
- const deadline = this.deps.now() + this.deps.machineReadyWaitMs;
- for (;;) {
- const lookup = await this.deps.targets.resolve(first).catch((error: unknown) => ({
- target: null,
- blocker: message(error),
- }));
- if (lookup.target) return null;
- if (this.deps.now() >= deadline)
- return `${where} was set up to run managed agents, but is not ready for them yet: ${lookup.blocker ?? 'it has not reached Switch'}.`;
- await this.deps.sleep(this.deps.pollMs);
- }
- }
-
// ── State ──────────────────────────────────────────────────────────────────
private async consoleState(
diff --git a/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration.ts b/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration.ts
index a4d59e5ea..eb5f90ef1 100644
--- a/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration.ts
+++ b/console/apps/switch-console-desktop/src/main/core/agent-migration/agent-migration.ts
@@ -2,6 +2,7 @@ import { execFile } from 'node:child_process';
import { join, posix } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import { promisify } from 'node:util';
+import { resolveAgentControllerBundlePath } from '@main/core/agent-runtime/impl/resolve-sidecar-bundle';
import { agentLaunchConfig } from '@main/core/agents/agent-launch-config';
import { getAgentLocation } from '@main/core/agents/agent-location';
import { resolveWorkdirFsFor } from '@main/core/agents/agent-workdir-fs';
@@ -39,7 +40,9 @@ import {
putManagedAgent,
revealAgentApiKey,
setManagedAgentDesiredState,
+ updateManagedAgent,
} from '@main/core/switch-servers/gateway-client';
+import { getServer } from '@main/core/switch-servers/servers-store';
import { withReachableWorkspaceSession } from '@main/core/workspaces/workspace-session';
import { events } from '@main/lib/events';
import { log } from '@main/lib/logger';
@@ -47,6 +50,7 @@ import type { Agent } from '@shared/core/agents/agents';
import { agentMigrationChannel } from '@shared/events/agentMigrationEvents';
import {
AgentMigrationService,
+ type MachineHealth,
type MigrationAgent,
type MigrationCredentialsPort,
type MigrationMachinePort,
@@ -177,14 +181,12 @@ async function resolveThisComputer(
);
if (overview.phase.kind !== 'running')
return refuse(
- `This computer’s controller is not running (${overview.phase.kind.replaceAll('_', ' ')}). See “This computer as a machine” on the server’s page.`
+ `This computer’s controller is not running (${overview.phase.kind.replaceAll('_', ' ')}); Console starts it again on its next check.`
);
if (remote?.kind === 'error')
return refuse(`Switch could not be asked about this computer’s controller: ${remote.message}`);
if (remote?.kind === 'ok' && remote.controller?.state !== 'online')
- return refuse(
- 'This computer’s controller has not reached Switch yet. Wait until the server’s page shows it Running.'
- );
+ return refuse('This computer’s controller has not reached Switch yet.');
const dataDir = embeddedControllerDataDir(serverId);
return {
display,
@@ -251,14 +253,12 @@ async function resolveSshHost(
return refuse(
overview.process?.kind === 'unknown'
? `Console cannot tell whether ${sshHost}’s controller runs: ${overview.process.reason}`
- : `${sshHost}’s controller is not running. Start it again from the host’s page.`
+ : `${sshHost}’s controller is not running; Console starts it again on its next check.`
);
if (remote?.kind === 'error')
return refuse(`Switch could not be asked about ${sshHost}’s controller: ${remote.message}`);
if (remote?.kind === 'ok' && remote.controller?.state !== 'online')
- return refuse(
- `${sshHost}’s controller has not reached Switch yet. Wait until the host’s page shows it Running.`
- );
+ return refuse(`${sshHost}’s controller has not reached Switch yet.`);
const dataDir = hostControllerDataDir(serverId);
return {
display,
@@ -316,6 +316,18 @@ const management: MigrationManagementPort = {
throw managementFailure('Switch did not start the agent on its machine', error);
}
},
+ place: async (workspaceId, switchAgentId, controllerId) => {
+ try {
+ await withReachableWorkspaceSession(workspaceId, (server) =>
+ updateManagedAgent(server, switchAgentId, { definition: null, controllerId })
+ );
+ } catch (error) {
+ throw managementFailure(
+ 'Switch did not place the agent on its machine’s new controller',
+ error
+ );
+ }
+ },
release: async (workspaceId, switchAgentId) => {
try {
return await withReachableWorkspaceSession(workspaceId, (server) =>
@@ -503,6 +515,121 @@ async function buildDefinition(agent: MigrationAgent) {
});
}
+let localControllerProtocol: Promise<string> | null = null;
+
+/** The controller protocol this Console's agents controller speaks, as the bundle reports it. */
+function controllerProtocol(): Promise<string> {
+ localControllerProtocol ??= execute(
+ process.execPath,
+ [resolveAgentControllerBundlePath(), '--protocol'],
+ { env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' }, timeout: 15_000 }
+ ).then(({ stdout }) => {
+ const protocol = stdout.trim();
+ if (!protocol) throw new Error('The agents controller did not report its protocol.');
+ return protocol;
+ });
+ localControllerProtocol.catch(() => {
+ localControllerProtocol = null;
+ });
+ return localControllerProtocol;
+}
+
+/**
+ * Why the server cannot take this Console's controller, or null when it can.
+ * A server that does not speak the controller's protocol refuses every call
+ * it makes, enrollment first, with HTTP 426.
+ */
+async function controllerRefusal(serverId: string): Promise<string | null> {
+ const server = await getServer(serverId);
+ if (!server) throw new Error('Console no longer knows this Switch server.');
+ const protocol = await controllerProtocol();
+ const response = await fetch(`${server.apiUrl}/v1/management/controllers/enroll`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', 'Switch-Controller-Protocol': protocol },
+ body: '{}',
+ signal: AbortSignal.timeout(15_000),
+ });
+ if (response.status !== 426) return null;
+ const accepts = response.headers.get('switch-controller-protocol-accepts');
+ return `${server.name} accepts agents controller protocol ${accepts ?? 'older than this Console’s'}, but this Console’s controller speaks ${protocol}. Upgrade the server to move agents onto it.`;
+}
+
+/** Repairs the controller an agent's machine runs for its server; see `AgentMigrationDeps.targets.heal`. */
+async function healMachine(agent: MigrationAgent): Promise<MachineHealth> {
+ const serverId = agent.serverId!;
+ const refusal = await controllerRefusal(serverId);
+ if (refusal) return { kind: 'incompatible', reason: refusal };
+ if (agent.sshHost) {
+ const sshHost = agent.sshHost;
+ const record = await hostControllerService.record(sshHost, serverId);
+ if (!record) return { kind: 'not-set-up' };
+ const overview = await hostControllerService.overview(sshHost, serverId, record.workspaceId);
+ const { process: running, remote } = overview;
+ if (running?.kind === 'unknown')
+ throw new Error(
+ `Console cannot tell whether ${sshHost}’s controller runs: ${running.reason}`
+ );
+ if (remote?.kind === 'error')
+ throw new Error(`Switch could not be asked about ${sshHost}’s controller: ${remote.message}`);
+ const gone =
+ (remote?.kind === 'ok' &&
+ (remote.controller === null || remote.controller.state === 'revoked')) ||
+ (running?.kind === 'stopped' && running.code === 3);
+ if (gone) {
+ log.warn('Switch revoked or forgot an SSH host’s controller; enrolling it again', {
+ event: 'agent_migration',
+ sshHost,
+ serverId,
+ controllerId: record.controllerId,
+ });
+ await hostControllerService.enrollAgain(sshHost, serverId);
+ return { kind: 'changed' };
+ }
+ const outdated = await hostControllerService.outdated(record);
+ if (running?.kind !== 'running' || outdated) {
+ log.info('Starting an SSH host’s controller again', {
+ event: 'agent_migration',
+ sshHost,
+ serverId,
+ reason: outdated ? 'older build' : 'not running',
+ });
+ await hostControllerService.restart(sshHost, serverId);
+ return { kind: 'changed' };
+ }
+ return { kind: 'unchanged' };
+ }
+ const overview = await embeddedControllerService.overview(serverId, agent.workspaceId);
+ if (overview.unsupportedReason)
+ return { kind: 'incompatible', reason: overview.unsupportedReason };
+ if (!overview.enrollment) return { kind: 'not-set-up' };
+ const remote = overview.remote;
+ if (remote?.kind === 'error')
+ throw new Error(
+ `Switch could not be asked about this computer’s controller: ${remote.message}`
+ );
+ if (
+ remote?.kind === 'ok' &&
+ (remote.controller === null || remote.controller.state === 'revoked')
+ ) {
+ log.warn('Switch revoked or forgot this computer’s controller; enrolling it again', {
+ event: 'agent_migration',
+ serverId,
+ controllerId: overview.enrollment.controllerId,
+ });
+ await embeddedControllerService.enrollAgain(serverId);
+ return { kind: 'changed' };
+ }
+ if (overview.phase.kind === 'taken_over')
+ throw new Error(
+ 'Another copy of this computer’s controller connected to Switch and took over, so this one is not started again.'
+ );
+ if (overview.phase.kind !== 'running' && overview.phase.kind !== 'restarting') {
+ await embeddedControllerService.restart(serverId);
+ return { kind: 'changed' };
+ }
+ return { kind: 'unchanged' };
+}
+
export const agentMigrationService = new AgentMigrationService({
agents: {
get: migrationAgent,
@@ -529,6 +656,7 @@ export const agentMigrationService = new AgentMigrationService({
await hostControllerService.enable(agent.sshHost, agent.serverId, agent.workspaceId);
else await embeddedControllerService.enable(agent.serverId, agent.workspaceId);
},
+ heal: (agent) => healMachine(agent),
},
management,
machine,
@@ -552,6 +680,9 @@ export const agentMigrationService = new AgentMigrationService({
controllerStopWaitMs: 60_000,
machineReadyWaitMs: 180_000,
unmanageableRecheckMs: 15 * 60_000,
+ minRetryMs: 60_000,
+ maxRetryMs: 15 * 60_000,
+ healIntervalMs: 5 * 60_000,
});
const AUTO_MIGRATION_INTERVAL_MS = 60_000;
diff --git a/console/apps/switch-console-desktop/src/main/core/agent-migration/controller.ts b/console/apps/switch-console-desktop/src/main/core/agent-migration/controller.ts
index 4a884ea8d..ec61ec6b7 100644
--- a/console/apps/switch-console-desktop/src/main/core/agent-migration/controller.ts
+++ b/console/apps/switch-console-desktop/src/main/core/agent-migration/controller.ts
@@ -1,5 +1,6 @@
import type {
AgentRunner,
+ MigrationOverview,
MigrationProblem,
NewAgentMachine,
} from '@shared/core/agent-migration/agent-migration';
@@ -16,6 +17,12 @@ export const agentMigrationController = createRPCController({
/** Why the agents the automatic move could not move did not. */
getProblems: (): MigrationProblem[] => agentMigrationService.migrationProblems(),
+ /** Where the automatic move stands, per machine and server, from what its passes found. */
+ getOverview: (): Promise<MigrationOverview> => agentMigrationService.overview(),
+
+ /** Runs a pass of the automatic move now rather than at the next minute. */
+ runNow: (): Promise<void> => agentMigrationService.migrateEverything(),
+
/** Runs the automatic move again now, asking Switch afresh about the agent. */
retry: (agentId: string): Promise<void> => {
agentMigrationService.recheck(agentId);
diff --git a/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.test.ts b/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.test.ts
index 9e11321d7..c08b14afa 100644
--- a/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.test.ts
@@ -235,6 +235,23 @@ describe('EmbeddedControllerService', () => {
expect(secrets.get(credentialSecretKey(SERVER))).toBe('swcc_second');
});
+ it('enrolls again when Switch revoked the machine', async () => {
+ const running = await enabled();
+ management.read.mockResolvedValue({
+ kind: 'ok',
+ controller: { name: 'build-box', description: null, state: 'revoked', lastSeenAt: null },
+ agents: [],
+ });
+ management.enroll.mockResolvedValueOnce({
+ serverId: SERVER,
+ apiUrl: 'https://switch.example.com',
+ controllerId: 'controller-3',
+ credential: 'swcc_third',
+ });
+ await running.enrollAgain(SERVER);
+ expect(storedRecord()).toMatchObject({ kind: 'enrolled', controllerId: 'controller-3' });
+ });
+
it('refuses to enroll again while Switch still lists the machine', async () => {
const running = await enabled();
management.read.mockResolvedValue({
diff --git a/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.ts b/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.ts
index 0ad6399e6..6b7849b4c 100644
--- a/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.ts
+++ b/console/apps/switch-console-desktop/src/main/core/embedded-controller/embedded-controller-service.ts
@@ -308,7 +308,7 @@ export class EmbeddedControllerService {
? `Switch could not be asked about this computer: ${remote.message}`
: 'This server no longer has agent management turned on.'
);
- if (remote.controller)
+ if (remote.controller && remote.controller.state !== 'revoked')
throw new Error(
'Switch still lists this computer as a machine. Turn it off and on again instead.'
);
diff --git a/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.test.ts b/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.test.ts
index 63b60f850..e8987108a 100644
--- a/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.test.ts
@@ -308,6 +308,18 @@ describe('the host as a machine afterwards', () => {
});
});
+describe('a host controller from an older Console', () => {
+ it('is outdated until it is started again on this build', async () => {
+ const service = new HostControllerService(deps());
+ await service.enable(HOST, SERVER, WORKSPACE);
+ const record = records.get(`${HOST}|${SERVER}`)!;
+ expect(await service.outdated(record)).toBe(false);
+ expect(
+ await service.outdated({ ...record, bundle: '/home/ada/sdk-host/agent-controller-old.mjs' })
+ ).toBe(true);
+ });
+});
+
describe('enrolling a host again that Switch no longer knows', () => {
it('wipes the old controller on the host, without a revoke, and enrolls it afresh', async () => {
const base = deps();
@@ -328,6 +340,25 @@ describe('enrolling a host again that Switch no longer knows', () => {
expect(records.get(`${HOST}|${SERVER}`)?.controllerId).toBe('controller-8');
});
+ it('enrolls a host whose controller Switch revoked afresh too', async () => {
+ const base = deps();
+ const service = new HostControllerService({
+ ...base,
+ management: {
+ ...base.management,
+ read: async () => ({
+ kind: 'ok',
+ controller: { state: 'revoked', lastSeenAt: null },
+ agents: [],
+ }),
+ },
+ });
+ await service.enable(HOST, SERVER, WORKSPACE);
+ host.enroll = { ok: true, controllerId: 'controller-9' };
+ await service.enrollAgain(HOST, SERVER);
+ expect(records.get(`${HOST}|${SERVER}`)?.controllerId).toBe('controller-9');
+ });
+
it('refuses while Switch still lists the host', async () => {
const service = new HostControllerService(deps());
await service.enable(HOST, SERVER, WORKSPACE);
diff --git a/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.ts b/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.ts
index 91c7253cc..7275d3c39 100644
--- a/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.ts
+++ b/console/apps/switch-console-desktop/src/main/core/host-controllers/host-controller-service.ts
@@ -274,6 +274,12 @@ export class HostControllerService {
});
}
+ /** Whether the host's controller runs an older bundle than this Console carries. */
+ async outdated(record: HostControllerRecord): Promise<boolean> {
+ const local = await this.deps.bundles.controller();
+ return posix.basename(record.bundle) !== `agent-controller-${local.hash}.mjs`;
+ }
+
/** Starts the controller again, on this build's bundle; its agents keep running meanwhile. */
async restart(sshHost: string, serverId: string): Promise<void> {
await this.exclusive(sshHost, serverId, async () => {
@@ -366,7 +372,7 @@ export class HostControllerService {
? `Switch could not be asked about ${sshHost}: ${remote.message}`
: 'This server no longer has agent management turned on.'
);
- if (remote.controller)
+ if (remote.controller && remote.controller.state !== 'revoked')
throw new Error(
`Switch still lists ${sshHost} as a machine. Turn it off and on again instead.`
);
diff --git a/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-presentation.test.ts b/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-presentation.test.ts
new file mode 100644
index 000000000..20dcb9b16
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-presentation.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import type { MigrationMachine } from '@shared/core/agent-migration/agent-migration';
+import { migrationMachineState, sortMachines } from './migration-presentation';
+
+const machine = (overrides: Partial<MigrationMachine>): MigrationMachine => ({
+ machine: 'this computer',
+ sshHost: null,
+ serverId: 'server-1',
+ total: 3,
+ moved: 3,
+ controller: { kind: 'ready' },
+ checkedAt: '2026-10-07T17:00:00Z',
+ problems: [],
+ ...overrides,
+});
+
+const problem = (name: string, message: string) => ({
+ agentId: name,
+ name,
+ machine: 'dev-vm',
+ message,
+});
+
+describe('migrationMachineState', () => {
+ it('is done once every agent moved', () => {
+ expect(migrationMachineState(machine({}))).toEqual({ tone: 'ok', label: 'Done', note: null });
+ });
+
+ it('says why a machine needs attention, once', () => {
+ expect(
+ migrationMachineState(
+ machine({ moved: 0, controller: { kind: 'failed', reason: 'ssh: timed out' } })
+ )
+ ).toEqual({ tone: 'error', label: 'Needs attention', note: 'ssh: timed out' });
+ });
+
+ it('tells a server too old for the controller apart from a failure', () => {
+ expect(
+ migrationMachineState(
+ machine({ moved: 0, controller: { kind: 'incompatible', reason: 'Upgrade it.' } })
+ )
+ ).toMatchObject({ tone: 'neutral', label: 'Server too old', note: 'Upgrade it.' });
+ });
+
+ it('counts stuck agents, naming the reason when there is one', () => {
+ expect(
+ migrationMachineState(machine({ moved: 2, problems: [problem('builder', 'refused')] }))
+ ).toEqual({ tone: 'warn', label: '1 stuck', note: 'refused' });
+ expect(
+ migrationMachineState(machine({ moved: 1, problems: [problem('a', 'x'), problem('b', 'y')] }))
+ ).toEqual({ tone: 'warn', label: '2 stuck', note: null });
+ });
+
+ it('is moving while agents remain and nothing is wrong', () => {
+ expect(migrationMachineState(machine({ moved: 1 }))).toMatchObject({ tone: 'busy' });
+ expect(migrationMachineState(machine({ moved: 1, controller: null }))).toMatchObject({
+ label: 'Not checked yet',
+ });
+ });
+});
+
+describe('sortMachines', () => {
+ it('puts machines needing attention first, then this computer, then hosts by name', () => {
+ const sorted = sortMachines([
+ machine({ sshHost: 'b-host', machine: 'b-host' }),
+ machine({ sshHost: 'a-host', machine: 'a-host' }),
+ machine({
+ sshHost: 'z-host',
+ machine: 'z-host',
+ moved: 0,
+ controller: { kind: 'failed', reason: 'x' },
+ }),
+ machine({}),
+ ]);
+ expect(sorted.map((m) => m.machine)).toEqual(['z-host', 'this computer', 'a-host', 'b-host']);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-presentation.ts b/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-presentation.ts
new file mode 100644
index 000000000..cbff80d99
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-presentation.ts
@@ -0,0 +1,39 @@
+import type { MigrationMachine } from '@shared/core/agent-migration/agent-migration';
+
+export type MigrationTone = 'ok' | 'busy' | 'warn' | 'error' | 'neutral';
+
+/** How one machine's row reads: a badge, and the one line under it that says what is wrong. */
+export function migrationMachineState(machine: MigrationMachine): {
+ tone: MigrationTone;
+ label: string;
+ note: string | null;
+} {
+ const controller = machine.controller;
+ if (controller?.kind === 'incompatible')
+ return { tone: 'neutral', label: 'Server too old', note: controller.reason };
+ if (controller?.kind === 'failed')
+ return { tone: 'error', label: 'Needs attention', note: controller.reason };
+ if (machine.moved === machine.total) return { tone: 'ok', label: 'Done', note: null };
+ if (machine.problems.length > 0)
+ return {
+ tone: 'warn',
+ label: `${machine.problems.length} stuck`,
+ note: machine.problems.length === 1 ? machine.problems[0]!.message : null,
+ };
+ if (controller === null) return { tone: 'neutral', label: 'Not checked yet', note: null };
+ return { tone: 'busy', label: 'Moving', note: null };
+}
+
+/** Machines needing attention first, then by machine (this computer first) and server. */
+export function sortMachines(machines: MigrationMachine[]): MigrationMachine[] {
+ const rank = (machine: MigrationMachine) => {
+ const tone = migrationMachineState(machine).tone;
+ return tone === 'error' ? 0 : tone === 'warn' ? 1 : 2;
+ };
+ return [...machines].sort(
+ (a, b) =>
+ rank(a) - rank(b) ||
+ (a.sshHost ?? '').localeCompare(b.sshHost ?? '') ||
+ a.serverId.localeCompare(b.serverId)
+ );
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-settings-page.tsx b/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-settings-page.tsx
new file mode 100644
index 000000000..ef05f0b87
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/agent-migration/migration-settings-page.tsx
@@ -0,0 +1,173 @@
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { CircleCheck, Monitor, RefreshCw, Server } from 'lucide-react';
+import { observer } from 'mobx-react-lite';
+import { switchServersStore } from '@renderer/features/switch-servers/switch-servers-store';
+import { PageHeader } from '@renderer/lib/components/page-header';
+import { failureText } from '@renderer/lib/errors/describe-failure';
+import { rpc } from '@renderer/lib/ipc';
+import { Button } from '@renderer/lib/ui/button';
+import { RelativeTime } from '@renderer/lib/ui/relative-time';
+import { StatusBadge, type StatusTone } from '@renderer/lib/ui/status-badge';
+import { cn } from '@renderer/utils/utils';
+import type { MigrationMachine } from '@shared/core/agent-migration/agent-migration';
+import { type MigrationTone, migrationMachineState, sortMachines } from './migration-presentation';
+
+const TONE: Record<MigrationTone, StatusTone> = {
+ neutral: 'neutral',
+ busy: 'info',
+ ok: 'success',
+ warn: 'warning',
+ error: 'danger',
+};
+
+const BAR: Record<MigrationTone, string> = {
+ neutral: 'bg-foreground-muted',
+ busy: 'bg-foreground-info',
+ ok: 'bg-foreground-success',
+ warn: 'bg-foreground-warning',
+ error: 'bg-foreground-destructive',
+};
+
+const OVERVIEW_KEY = ['agent-migration-overview'];
+
+/**
+ * Where the automatic move of this Console's agents onto managed machines
+ * stands: one row per machine and server, with a counter, and what keeps any
+ * agent from moving. Nothing here moves agents: Console does that by itself.
+ */
+export const MigrationSettingsPage = observer(function MigrationSettingsPage() {
+ const overview = useQuery({
+ queryKey: OVERVIEW_KEY,
+ queryFn: () => rpc.agentMigration.getOverview(),
+ refetchInterval: (query) => (query.state.data?.running ? 2_000 : 10_000),
+ });
+ const runNow = useMutation({
+ mutationFn: () => rpc.agentMigration.runNow(),
+ onSettled: () => overview.refetch(),
+ });
+ const serverName = (serverId: string) =>
+ switchServersStore.servers.find((server) => server.id === serverId)?.name ?? serverId;
+ const data = overview.data;
+ const running = runNow.isPending || data?.running === true;
+
+ return (
+ <div className="space-y-6 pb-10">
+ <PageHeader
+ sticky
+ title="Managed agents"
+ description="Console moves each of your agents onto a managed machine by itself, on this computer and on your SSH hosts, so Switch runs them. This shows how far that has got."
+ />
+ <div className="flex items-center justify-between gap-3">
+ <p className="text-xs text-foreground-muted">
+ {running ? (
+ 'Checking now…'
+ ) : data?.lastPassAt ? (
+ <>
+ Last checked <RelativeTime value={data.lastPassAt} ago />. Checked again every minute.
+ </>
+ ) : (
+ 'Not checked yet.'
+ )}
+ </p>
+ <Button variant="outline" size="sm" disabled={running} onClick={() => runNow.mutate()}>
+ <RefreshCw className={cn('size-4', running && 'animate-spin')} /> Check now
+ </Button>
+ </div>
+ {overview.error && (
+ <p className="text-xs text-foreground-error">
+ {failureText(overview.error, 'Could not read where the move stands.')}
+ </p>
+ )}
+ {data && data.machines.length === 0 && (
+ <p className="text-sm text-foreground-muted">
+ No agent of yours is on a server with agent management.
+ </p>
+ )}
+ {data && data.machines.length > 0 && (
+ <ul className="divide-y divide-border rounded-lg border border-border">
+ {sortMachines(data.machines).map((machine) => (
+ <MachineRow
+ key={`${machine.sshHost ?? ''}:${machine.serverId}`}
+ machine={machine}
+ serverName={serverName(machine.serverId)}
+ />
+ ))}
+ </ul>
+ )}
+ {data && (data.leftAlone > 0 || data.unasked > 0) && (
+ <div className="space-y-1 text-xs text-foreground-muted">
+ {data.leftAlone > 0 && (
+ <p>
+ {data.leftAlone} {data.leftAlone === 1 ? 'agent stays' : 'agents stay'} in Console:
+ someone else owns them, or their server has no agent management.
+ </p>
+ )}
+ {data.unasked > 0 && (
+ <p>
+ Switch could not be asked about {data.unasked}{' '}
+ {data.unasked === 1 ? 'agent' : 'agents'}: the server is stopped or unreachable, or no
+ longer knows the agent. Tried again later.
+ </p>
+ )}
+ </div>
+ )}
+ </div>
+ );
+});
+
+function MachineRow({ machine, serverName }: { machine: MigrationMachine; serverName: string }) {
+ const state = migrationMachineState(machine);
+ const Icon = machine.sshHost === null ? Monitor : Server;
+ const share = machine.total ? (machine.moved / machine.total) * 100 : 0;
+ const name = machine.sshHost ?? 'This computer';
+ return (
+ <li className="space-y-1.5 px-3 py-2.5">
+ <div className="flex items-center gap-2.5">
+ <Icon className="size-4 shrink-0 text-foreground-muted" />
+ <span className="min-w-0 flex-1 truncate text-sm text-foreground">
+ {name}
+ <span className="text-foreground-muted"> · {serverName}</span>
+ </span>
+ <span className="shrink-0 text-xs text-foreground-muted tabular-nums">
+ {machine.moved}/{machine.total}
+ </span>
+ {state.tone === 'ok' ? (
+ <CircleCheck className="size-4 shrink-0 text-foreground-success" aria-label="Done" />
+ ) : (
+ <StatusBadge tone={TONE[state.tone]} className="shrink-0">
+ {state.label}
+ </StatusBadge>
+ )}
+ </div>
+ <div
+ className="h-1 w-full overflow-hidden rounded-full bg-border"
+ role="progressbar"
+ aria-label={`${name} for ${serverName}: ${machine.moved} of ${machine.total} moved`}
+ aria-valuemin={0}
+ aria-valuemax={machine.total}
+ aria-valuenow={machine.moved}
+ >
+ <div
+ className={cn(
+ 'h-full rounded-full transition-all duration-500',
+ BAR[state.tone],
+ state.tone === 'busy' && 'animate-pulse'
+ )}
+ style={{ width: `${share}%` }}
+ />
+ </div>
+ {state.note && (
+ <p className="pl-6.5 text-xs break-words text-foreground-muted">{state.note}</p>
+ )}
+ {!state.note && machine.problems.length > 1 && (
+ <ul className="space-y-0.5 pl-6.5 text-xs text-foreground-muted">
+ {machine.problems.map((problem) => (
+ <li key={problem.agentId} className="break-words">
+ <span className="text-foreground">{problem.name}</span>: {problem.message}
+ </li>
+ ))}
+ </ul>
+ )}
+ </li>
+ );
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx b/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx
index 0d0e5ebaf..c826c37f4 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx
@@ -1,4 +1,5 @@
import React, { useCallback } from 'react';
+import { MigrationSettingsPage } from '@renderer/features/agent-migration/migration-settings-page';
import { RemoteHostsSettingsPage } from '@renderer/features/remote-hosts/views/remote-hosts-view';
import { PageHeader } from '@renderer/lib/components/page-header';
import { PageContent, PageLayout, PageSidebarMenu } from '@renderer/lib/components/page-layout';
@@ -25,6 +26,7 @@ export type SettingsPageTab =
| 'browser'
| 'interface'
| 'remote-hosts'
+ | 'managed-agents'
| 'docs';
// ---------------------------------------------------------------------------
@@ -77,6 +79,7 @@ const TAB_CONTENT: Partial<Record<SettingsPageTab, () => React.ReactNode>> = {
'clis-models': () => <AgentsSettingsPage />,
interface: () => <InterfaceSettingsPage />,
'remote-hosts': () => <RemoteHostsSettingsPage />,
+ 'managed-agents': () => <MigrationSettingsPage />,
};
/**
@@ -110,6 +113,7 @@ export function SettingsPage({
{ id: 'general', label: 'General' },
{ id: 'clis-models', label: 'Agent providers' },
{ id: 'remote-hosts', label: 'Remote hosts' },
+ { id: 'managed-agents', label: 'Managed agents' },
{ id: 'interface', label: 'Interface' },
{ id: 'docs', label: 'Docs', isExternal: true },
];
diff --git a/console/apps/switch-console-desktop/src/renderer/tests/browser/migration-settings-page.test.tsx b/console/apps/switch-console-desktop/src/renderer/tests/browser/migration-settings-page.test.tsx
new file mode 100644
index 000000000..933729634
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/tests/browser/migration-settings-page.test.tsx
@@ -0,0 +1,133 @@
+/**
+ * The Settings page that shows how far the automatic move to managed agents
+ * has got: one row per machine and server, and what keeps agents from moving.
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, expect, it, vi } from 'vitest';
+import type { MigrationOverview } from '@shared/core/agent-migration/agent-migration';
+
+const agentMigration = vi.hoisted(() => ({
+ getOverview: vi.fn<() => Promise<MigrationOverview>>(),
+ runNow: vi.fn(async () => {}),
+}));
+
+vi.mock('@renderer/lib/ipc', () => ({
+ events: { on: () => () => {} },
+ rpc: { agentMigration },
+}));
+vi.mock('@renderer/features/switch-servers/switch-servers-store', () => ({
+ switchServersStore: {
+ servers: [
+ { id: 'pilot', name: 'Switch Pilot' },
+ { id: 'local', name: 'Local dev' },
+ ],
+ },
+}));
+
+import { MigrationSettingsPage } from '@renderer/features/agent-migration/migration-settings-page';
+
+let container: HTMLDivElement | null = null;
+let root: Root | null = null;
+
+async function render(overview: MigrationOverview): Promise<HTMLDivElement> {
+ agentMigration.getOverview.mockResolvedValue(overview);
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+ const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+ await act(async () =>
+ root!.render(
+ <QueryClientProvider client={client}>
+ <MigrationSettingsPage />
+ </QueryClientProvider>
+ )
+ );
+ await vi.waitFor(() => expect(container!.querySelector('ul')).not.toBeNull());
+ return container;
+}
+
+afterEach(async () => {
+ if (root) await act(async () => root!.unmount());
+ container?.remove();
+ container = null;
+ root = null;
+});
+
+it('lists each machine and server with its counter, the troubled ones first, and why', async () => {
+ const el = await render({
+ machines: [
+ {
+ machine: 'this computer',
+ sshHost: null,
+ serverId: 'pilot',
+ total: 6,
+ moved: 6,
+ controller: { kind: 'ready' },
+ checkedAt: '2026-10-07T17:00:00Z',
+ problems: [],
+ },
+ {
+ machine: 'dev-vm',
+ sshHost: 'dev-vm',
+ serverId: 'pilot',
+ total: 18,
+ moved: 0,
+ controller: { kind: 'failed', reason: 'ssh: connect to host dev-vm: timed out' },
+ checkedAt: '2026-10-07T17:00:00Z',
+ problems: [],
+ },
+ {
+ machine: 'this computer',
+ sshHost: null,
+ serverId: 'local',
+ total: 17,
+ moved: 0,
+ controller: { kind: 'incompatible', reason: 'Local dev accepts protocol 1-1.' },
+ checkedAt: '2026-10-07T17:00:00Z',
+ problems: [],
+ },
+ ],
+ leftAlone: 4,
+ unasked: 2,
+ running: false,
+ lastPassAt: '2026-10-07T17:00:00Z',
+ });
+ const rows = [...el.querySelectorAll('li')].map((li) => li.textContent);
+ expect(rows[0]).toContain('dev-vm · Switch Pilot');
+ expect(rows[0]).toContain('0/18');
+ expect(rows[0]).toContain('ssh: connect to host dev-vm: timed out');
+ expect(rows[1]).toContain('This computer · Local dev');
+ expect(rows[1]).toContain('Server too old');
+ expect(rows[2]).toContain('This computer · Switch Pilot');
+ expect(rows[2]).toContain('6/6');
+ expect(el.textContent).toContain('4 agents stay in Console');
+ expect(el.textContent).toContain('Switch could not be asked about 2 agents');
+});
+
+it('runs a check when asked', async () => {
+ const el = await render({
+ machines: [
+ {
+ machine: 'this computer',
+ sshHost: null,
+ serverId: 'pilot',
+ total: 1,
+ moved: 1,
+ controller: { kind: 'ready' },
+ checkedAt: null,
+ problems: [],
+ },
+ ],
+ leftAlone: 0,
+ unasked: 0,
+ running: false,
+ lastPassAt: null,
+ });
+ const button = [...el.querySelectorAll('button')].find((b) =>
+ b.textContent?.includes('Check now')
+ )!;
+ await act(async () => button.click());
+ expect(agentMigration.runNow).toHaveBeenCalled();
+});
diff --git a/console/apps/switch-console-desktop/src/shared/core/agent-migration/agent-migration.ts b/console/apps/switch-console-desktop/src/shared/core/agent-migration/agent-migration.ts
index 19865719e..6ea6dd4e8 100644
--- a/console/apps/switch-console-desktop/src/shared/core/agent-migration/agent-migration.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/agent-migration/agent-migration.ts
@@ -98,6 +98,38 @@ export type MigrationProblem = {
message: string;
};
+/** The controller one machine runs for one server, as the last automatic pass found it. */
+export type MigrationControllerState =
+ | { kind: 'ready' }
+ /** The server cannot take this Console's controller; its agents are left as they are. */
+ | { kind: 'incompatible'; reason: string }
+ | { kind: 'failed'; reason: string };
+
+/** One machine's agents for one server: how many moved, and what keeps the rest. */
+export type MigrationMachine = {
+ /** "this computer", or the SSH host's name. */
+ machine: string;
+ sshHost: string | null;
+ serverId: string;
+ total: number;
+ moved: number;
+ /** Null until a pass has looked at the machine. */
+ controller: MigrationControllerState | null;
+ checkedAt: string | null;
+ problems: MigrationProblem[];
+};
+
+/** Where the automatic move to managed agents stands. */
+export type MigrationOverview = {
+ machines: MigrationMachine[];
+ /** Agents left as they are: someone else's, or on a server without agent management. */
+ leftAlone: number;
+ /** Agents whose server could not be asked whether they can move; tried again later. */
+ unasked: number;
+ running: boolean;
+ lastPassAt: string | null;
+};
+
export type AgentMigrationEvent = {
agentId: string;
runner: AgentRunner;
diff --git a/console/packages/agent-controller/src/main.ts b/console/packages/agent-controller/src/main.ts
index 0deeb1693..25e3c02e5 100644
--- a/console/packages/agent-controller/src/main.ts
+++ b/console/packages/agent-controller/src/main.ts
@@ -44,7 +44,7 @@ import {
probeProvider,
} from './runtime';
import { AgentRuntimes } from './runtimes';
-import type { ControllerInfoChange } from './schemas';
+import { type ControllerInfoChange, PROTOCOL_VERSION } from './schemas';
import {
CONTROLLER_CREDENTIAL,
defaultSecretStoreKind,
@@ -647,6 +647,9 @@ export async function main(argv: string[]): Promise<number> {
case '--version':
process.stdout.write(`${VERSION}\n`);
return 0;
+ case '--protocol':
+ process.stdout.write(`${PROTOCOL_VERSION}\n`);
+ return 0;
default:
throw new UsageError(`Unknown command '${command}'.`);
}