fix(remote-control): exit the web server when the relay takes the device offline (#4182)

* fix(remote-control): exit the web server when the relay takes the device offline

* test(cli): satisfy the remote-control handle contract in tui web tests

Author: sailist

apps/kimi-code/src/cli/sub/web/remote-control.ts

@@ -23,6 +23,7 @@ export {
 } from '@moonshot-ai/remote-control';
 export type {
   ParsedRawHttpRequest,
+  RemoteControlCloseReason,
   RemoteControlHandle,
   RemoteControlLock,
   RemoteControlLockInfo,
@@ -84,6 +85,8 @@ export function formatRemoteControlStatus(status: RemoteControlStatus): string {
       return `  ${value('✓')} ${label('Connected to relay, waiting for remote devices…')}\n`;
     case 'relay_disconnected':
       return `  ${value('!')} ${label('Relay disconnected; reconnecting…')}\n`;
+    case 'relay_terminated':
+      return `  ${value('✕')} ${label('Taken offline from the web; exiting…')}\n`;
     case 'device_connected':
       return `  ${value('✓')} ${label('Remote device connected (1 active session)')}\n`;
     case 'device_disconnected':

apps/kimi-code/src/cli/sub/web/run.ts

@@ -76,9 +76,14 @@ export interface WebCliOptions extends ServerCliOptions {
   remoteControl?: boolean;
 }
 
+export interface ForegroundControls {
+  /** Ask the foreground runner to shut the server down and exit (like SIGINT). */
+  requestShutdown(reason: string): void;
+}
+
 export interface StartForegroundHooks {
   /** Fires once the server is listening, before the foreground runner blocks. */
-  onReady?: (origin: string) => void | Promise<void>;
+  onReady?: (origin: string, controls?: ForegroundControls) => void | Promise<void>;
   onShutdown?: (reason: string) => void | Promise<void>;
 }
 
@@ -202,7 +207,7 @@ export async function handleWebCommand(
   const run = deps.startServerForeground ?? startServerForeground;
   let remoteControl: RemoteControlHandle | undefined;
   await run(parsed, {
-    onReady: async (origin) => {
+    onReady: async (origin, controls) => {
       // Resolve the persistent token only once the server is up: a fresh
       // server writes `server.token` on first boot, so reading it beforehand
       // would miss first-time starts and the browser would hit the auth gate.
@@ -232,6 +237,19 @@ export async function handleWebCommand(
           stderr: deps.stderr,
           onStatus,
         });
+        void remoteControl.closed.then(
+          (reason) => {
+            if (reason === 'user_requested') {
+              controls?.requestShutdown('remote_control_user_requested');
+            }
+          },
+          (error) => {
+            deps.stderr.write(
+              `Remote Control lock release failed: ${error instanceof Error ? error.message : String(error)}\n`,
+            );
+            controls?.requestShutdown('remote_control_closed');
+          },
+        );
         const qrCode = await generateRemoteControlQr(remoteControl.url, dataDir);
         deps.stdout.write(
           formatRemoteControlOutput({
@@ -404,7 +422,9 @@ async function runServerInProcess(
   running.logger.info({ address: running.address }, 'server ready');
 
   try {
-    await hooks.onReady?.(running.address);
+    await hooks.onReady?.(running.address, {
+      requestShutdown: (reason) => void shutdown(reason),
+    });
   } catch (error) {
     try {
       await hooks.onShutdown?.('startup_failed');

apps/kimi-code/src/tui/commands/web.ts

@@ -57,7 +57,7 @@ export async function handleRemoteControlCommand(host: SlashCommandHost): Promis
     let remoteControl: Awaited<ReturnType<typeof startRemoteControl>> | undefined;
     try {
       await startServerForeground(options, {
-        onReady: async (origin) => {
+        onReady: async (origin, controls) => {
           const dataDir = getDataDir();
           const token = tryResolveServerToken(dataDir);
           if (token === undefined) throw new Error('Unable to read the local server token.');
@@ -78,6 +78,19 @@ export async function handleRemoteControlCommand(host: SlashCommandHost): Promis
             configuredOAuthHost: persisted?.oauthHost,
             onStatus,
           });
+          void remoteControl.closed.then(
+            (reason) => {
+              if (reason === 'user_requested') {
+                controls?.requestShutdown('remote_control_user_requested');
+              }
+            },
+            (error) => {
+              process.stderr.write(
+                `Remote Control lock release failed: ${formatErrorMessage(error)}\n`,
+              );
+              controls?.requestShutdown('remote_control_closed');
+            },
+          );
           const url = buildRemoteControlUrl(
             remoteControl.deviceId,
             session?.id,

apps/kimi-code/test/cli/web/remote-control.test.ts

@@ -59,6 +59,9 @@ describe('Remote Control output', () => {
   it('formats relay and device lifecycle states', () => {
     expect(formatRemoteControlStatus('relay_connected').toLowerCase()).toContain('connected');
     expect(formatRemoteControlStatus('relay_disconnected')).toContain('disconnected');
+    expect(formatRemoteControlStatus('relay_terminated')).toContain('offline');
+    expect(formatRemoteControlStatus('relay_terminated')).toContain('exiting');
+    expect(formatRemoteControlStatus('relay_terminated')).not.toContain('reconnecting');
     expect(formatRemoteControlStatus('device_connected').toLowerCase()).toContain('connected');
     expect(formatRemoteControlStatus('device_disconnected')).toContain('disconnected');
   });

apps/kimi-code/test/cli/web/web.test.ts

@@ -19,6 +19,10 @@ import { resetCapabilitiesCache, setCapabilities } from '@moonshot-ai/pi-tui';
 
 import { registerWebCommand } from '#/cli/sub/web';
 import type { LegacyKillDeps } from '#/cli/sub/web/legacy-kill';
+import type {
+  RemoteControlCloseReason,
+  RemoteControlStatus,
+} from '#/cli/sub/web/remote-control';
 import type { WebCommandDeps } from '#/cli/sub/web/run';
 import type { ParsedServerOptions } from '#/cli/sub/web/shared';
 import { darkColors } from '#/tui/theme/colors';
@@ -464,6 +468,100 @@ describe('`kimi web` opens the browser', () => {
     ).rejects.toThrow('--remote-control requires a loopback host.');
   });
 
+  it('requests foreground shutdown when the relay takes the device offline', async () => {
+    const { handleWebCommand } = await import('#/cli/sub/web/run');
+    const home = mkdtempSync(join(tmpdir(), 'kimi-web-rc-'));
+    vi.stubEnv('KIMI_CODE_HOME', home);
+    const { stdout, stderr, readStdout } = makeIo();
+    const requestShutdown = vi.fn();
+    const runner: ForegroundRunner = async (_options, hooks) => {
+      await hooks?.onReady?.('http://127.0.0.1:58627', { requestShutdown });
+      return undefined as never;
+    };
+    let emitStatus: ((status: RemoteControlStatus) => void) | undefined;
+    let resolveClosed: ((reason: RemoteControlCloseReason) => void) | undefined;
+    const startRemoteControl: WebCommandDeps['startRemoteControl'] = async (options) => {
+      emitStatus = options.onStatus;
+      return {
+        deviceId: 'device-1',
+        deviceName: 'example-device',
+        url: 'https://example.test/devices/device-1/?rc=1&from=kimi_code_cli',
+        relayOrigin: 'https://example.test',
+        closed: new Promise<RemoteControlCloseReason>((resolve) => {
+          resolveClosed = resolve;
+        }),
+        close: async () => {},
+      };
+    };
+
+    try {
+      await handleWebCommand(
+        { remoteControl: true, open: false },
+        {
+          startServerForeground: runner,
+          startRemoteControl,
+          resolveToken: () => 'tok',
+          openUrl: vi.fn(),
+          stdout,
+          stderr,
+        },
+      );
+
+      emitStatus?.('relay_terminated');
+      resolveClosed?.('user_requested');
+      await vi.waitFor(() => {
+        expect(requestShutdown).toHaveBeenCalledWith('remote_control_user_requested');
+      });
+      expect(readStdout()).toContain('offline');
+      expect(readStdout()).not.toContain('reconnecting');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  it('does not request shutdown when the tunnel closes locally', async () => {
+    const { handleWebCommand } = await import('#/cli/sub/web/run');
+    const home = mkdtempSync(join(tmpdir(), 'kimi-web-rc-'));
+    vi.stubEnv('KIMI_CODE_HOME', home);
+    const { stdout, stderr } = makeIo();
+    const requestShutdown = vi.fn();
+    const runner: ForegroundRunner = async (_options, hooks) => {
+      await hooks?.onReady?.('http://127.0.0.1:58627', { requestShutdown });
+      return undefined as never;
+    };
+    let resolveClosed: ((reason: RemoteControlCloseReason) => void) | undefined;
+    const startRemoteControl: WebCommandDeps['startRemoteControl'] = async () => ({
+      deviceId: 'device-1',
+      deviceName: 'example-device',
+      url: 'https://example.test/devices/device-1/?rc=1&from=kimi_code_cli',
+      relayOrigin: 'https://example.test',
+      closed: new Promise<RemoteControlCloseReason>((resolve) => {
+        resolveClosed = resolve;
+      }),
+      close: async () => {},
+    });
+
+    try {
+      await handleWebCommand(
+        { remoteControl: true, open: false },
+        {
+          startServerForeground: runner,
+          startRemoteControl,
+          resolveToken: () => 'tok',
+          openUrl: vi.fn(),
+          stdout,
+          stderr,
+        },
+      );
+
+      resolveClosed?.('local_close');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(requestShutdown).not.toHaveBeenCalled();
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
   it('shows --remote-control in help', () => {
     const remoteControlOption = makeProgram()
       .commands.find((command) => command.name() === 'web')!

apps/kimi-code/test/tui/commands/web.test.ts

@@ -205,6 +205,7 @@ describe('handleRemoteControlCommand', () => {
       deviceName: 'example-device',
       url: entryUrl,
       relayOrigin: 'https://code-rc.kimi.com',
+      closed: new Promise(() => {}),
       close,
     });
     mocks.startServerForeground.mockImplementation(
@@ -275,6 +276,7 @@ describe('handleRemoteControlCommand', () => {
       deviceName: 'example-device',
       url: entryUrl,
       relayOrigin: 'https://code-rc.kimi.com',
+      closed: new Promise(() => {}),
       close,
     });
     mocks.startServerForeground.mockImplementation(

packages/remote-control/src/remote-control.ts

@@ -92,9 +92,12 @@ export interface ParsedRawHttpRequest {
 export type RemoteControlStatus =
   | 'relay_connected'
   | 'relay_disconnected'
+  | 'relay_terminated'
   | 'device_connected'
   | 'device_disconnected';
 
+export type RemoteControlCloseReason = 'local_close' | 'user_requested';
+
 export interface RemoteControlOptions {
   readonly homeDir: string;
   readonly localOrigin: string;
@@ -114,7 +117,7 @@ export interface RemoteControlHandle {
   readonly deviceName: string;
   readonly url: string;
   readonly relayOrigin: string;
-  readonly closed: Promise<void>;
+  readonly closed: Promise<RemoteControlCloseReason>;
   close(): Promise<void>;
 }
 
@@ -316,8 +319,9 @@ export async function startRemoteControl(
     await lock.release();
     throw error;
   }
-  const closed = client.closed.then(async () => {
+  const closed = client.closed.then(async (reason) => {
     await lock.release();
+    return reason;
   });
   return {
     deviceId,
@@ -352,6 +356,7 @@ class RemoteControlClient {
   private readonly pingIntervalMs: number;
   private readonly silenceTimeoutMs: number;
   private stopped = false;
+  private userRequested = false;
   private connected = false;
   private relayOnline = false;
   private runPromise: Promise<void> | undefined;
@@ -387,8 +392,10 @@ class RemoteControlClient {
     await initial;
   }
 
-  get closed(): Promise<void> {
-    return this.runPromise ?? Promise.resolve();
+  get closed(): Promise<RemoteControlCloseReason> {
+    return (this.runPromise ?? Promise.resolve()).then(() =>
+      this.userRequested ? 'user_requested' : 'local_close',
+    );
   }
 
   async close(): Promise<void> {
@@ -550,7 +557,10 @@ class RemoteControlClient {
     }
     if (message.type === 'disconnect') {
       const reason = stringField(message.payload, 'reason');
-      if (reason === 'user_requested') this.stopped = true;
+      if (reason === 'user_requested') {
+        this.stopped = true;
+        this.userRequested = true;
+      }
       if (reason === 'server_shutting_down') this.reconnectImmediately = true;
       this.closeCycle();
     }
@@ -722,7 +732,7 @@ class RemoteControlClient {
     this.http?.close();
     if (this.relayOnline) {
       this.relayOnline = false;
-      this.onStatus('relay_disconnected');
+      this.onStatus(this.userRequested ? 'relay_terminated' : 'relay_disconnected');
     }
     this.management = undefined;
     this.http = undefined;

packages/remote-control/test/remote-control.test.ts

@@ -817,6 +817,47 @@ describe('Remote Control single-instance lock', () => {
     expect(existsSync(remoteControlLockPath(homeDir))).toBe(false);
   });
 
+  it('reports a terminal status and close reason on user_requested only', async () => {
+    const homeDir = await createRemoteControlHome(TOKEN.refreshToken);
+    const relay = await startAuthRelay();
+    const statuses: string[] = [];
+    let handle: RemoteControlHandle | undefined;
+    cleanups.push(async () => handle?.close());
+
+    handle = await startRemoteControl({
+      homeDir,
+      localOrigin: 'http://127.0.0.1:58627',
+      localServerToken: 'local-server-token',
+      clientVersion: CLIENT_VERSION,
+      relayOrigin: `http://127.0.0.1:${relay.port}`,
+      stderr: { write: () => true },
+      onStatus: (status) => statuses.push(status),
+    });
+
+    relay.managementSockets.at(-1)!.send(
+      JSON.stringify({ type: 'disconnect', payload: { reason: 'user_requested' } }),
+    );
+    await expect(handle.closed).resolves.toBe('user_requested');
+    expect(statuses).toEqual(['relay_connected', 'relay_terminated']);
+
+    const localStatuses: string[] = [];
+    let second: RemoteControlHandle | undefined;
+    cleanups.push(async () => second?.close());
+    second = await startRemoteControl({
+      homeDir,
+      localOrigin: 'http://127.0.0.1:58627',
+      localServerToken: 'local-server-token',
+      clientVersion: CLIENT_VERSION,
+      relayOrigin: `http://127.0.0.1:${relay.port}`,
+      stderr: { write: () => true },
+      onStatus: (status) => localStatuses.push(status),
+    });
+    const closing = second.close();
+    await expect(second.closed).resolves.toBe('local_close');
+    await closing;
+    expect(localStatuses).toEqual(['relay_connected', 'relay_disconnected']);
+  });
+
   it('does not remove a successor lock when closing', async () => {
     const homeDir = await createRemoteControlHome(TOKEN.refreshToken);
     const relay = await startAuthRelay();