feat(companion): add disconnect metadata to connection snapshots

src/companion/platformClients.integration.test.ts

@@ -271,6 +271,8 @@ describe('platform clients integration', () => {
       pendingEventWaitCount: 0,
       hasPendingWork: false,
       idle: true,
+      lastDisconnectCode: undefined,
+      lastDisconnectReason: undefined,
     });
 
     const unsubscribe = client.subscribeEvents(() => undefined);
@@ -283,6 +285,8 @@ describe('platform clients integration', () => {
       pendingEventWaitCount: 1,
       hasPendingWork: true,
       idle: false,
+      lastDisconnectCode: undefined,
+      lastDisconnectReason: undefined,
     });
 
     client.clearEventSubscriptions();
@@ -294,6 +298,8 @@ describe('platform clients integration', () => {
       pendingEventWaitCount: 0,
       hasPendingWork: false,
       idle: true,
+      lastDisconnectCode: undefined,
+      lastDisconnectReason: undefined,
     });
 
     unsubscribe();

src/companion/platformClients.test.ts

@@ -100,6 +100,8 @@ function createRuntimeMock(): {
     pendingEventWaitCount: 1,
     hasPendingWork: true,
     idle: false,
+    lastDisconnectCode: 1000,
+    lastDisconnectReason: 'normal closure',
   }));
   const waitForAgentStream = vi.fn(async () => ({ token: 'streamed' }));
   const waitForAgentTyping = vi.fn(async () => ({ active: true }));
@@ -443,6 +445,8 @@ describe('platform companion clients', () => {
       pendingEventWaitCount: 1,
       hasPendingWork: true,
       idle: false,
+      lastDisconnectCode: 1000,
+      lastDisconnectReason: 'normal closure',
     });
   });
 

src/companion/runtimeClient.test.ts

@@ -762,6 +762,8 @@ describe('CompanionRuntimeClient', () => {
       pendingEventWaitCount: 1,
       hasPendingWork: true,
       idle: false,
+      lastDisconnectCode: undefined,
+      lastDisconnectReason: undefined,
     });
 
     client.clearEventSubscriptions();
@@ -773,6 +775,70 @@ describe('CompanionRuntimeClient', () => {
       pendingEventWaitCount: 0,
       hasPendingWork: false,
       idle: true,
+      lastDisconnectCode: undefined,
+      lastDisconnectReason: undefined,
+    });
+  });
+
+  it('connection snapshot tracks manual disconnect code and reason', () => {
+    const client = new CompanionRuntimeClient({
+      url: 'ws://127.0.0.1:1',
+    });
+
+    client.disconnect(4100, 'manual stop');
+
+    expect(client.getConnectionSnapshot()).toEqual({
+      connected: false,
+      eventSubscriptionCount: 0,
+      pendingRequestCount: 0,
+      pendingEventWaitCount: 0,
+      hasPendingWork: false,
+      idle: true,
+      lastDisconnectCode: 4100,
+      lastDisconnectReason: 'manual stop',
+    });
+  });
+
+  it('connection snapshot tracks transport close code and reason', async () => {
+    class FakeWebSocket extends EventEmitter {
+      readyState: number = WebSocket.CONNECTING;
+
+      constructor() {
+        super();
+        queueMicrotask(() => {
+          this.readyState = WebSocket.OPEN;
+          this.emit('open');
+        });
+      }
+
+      send(_payload: string, callback?: (error?: Error) => void): void {
+        callback?.();
+      }
+
+      close(_code?: number, _reason?: string): void {
+        this.readyState = WebSocket.CLOSED;
+        this.emit('close', 4001, Buffer.from('transport closed'));
+      }
+    }
+
+    const client = new CompanionRuntimeClient({
+      url: 'ws://127.0.0.1:1',
+      websocketFactory: () => new FakeWebSocket() as unknown as WebSocket,
+    });
+    await client.connect();
+
+    const ws = (client as unknown as { ws: WebSocket | null }).ws;
+    ws?.close();
+
+    expect(client.getConnectionSnapshot()).toEqual({
+      connected: false,
+      eventSubscriptionCount: 0,
+      pendingRequestCount: 0,
+      pendingEventWaitCount: 0,
+      hasPendingWork: false,
+      idle: true,
+      lastDisconnectCode: 4001,
+      lastDisconnectReason: 'transport closed',
     });
   });
 

src/companion/runtimeClient.ts

@@ -66,6 +66,8 @@ export interface ConnectionSnapshot {
   pendingEventWaitCount: number;
   hasPendingWork: boolean;
   idle: boolean;
+  lastDisconnectCode?: number;
+  lastDisconnectReason?: string;
 }
 
 export interface ClearEventSubscriptionsResult {
@@ -313,6 +315,8 @@ export class CompanionRuntimeClient {
   private pending = new Map<number, PendingRequest>();
   private readonly eventHandlers = new Set<CompanionEventHandler>();
   private readonly pendingEventWaits = new Set<(error: Error) => void>();
+  private lastDisconnectCode: number | undefined;
+  private lastDisconnectReason: string | undefined;
 
   constructor(options: CompanionRuntimeClientOptions) {
     const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
@@ -374,6 +378,8 @@ export class CompanionRuntimeClient {
       pendingEventWaitCount: this.pendingEventWaitCount,
       hasPendingWork: this.hasPendingWork,
       idle: this.idle,
+      lastDisconnectCode: this.lastDisconnectCode,
+      lastDisconnectReason: this.lastDisconnectReason,
     };
   }
 
@@ -405,7 +411,10 @@ export class CompanionRuntimeClient {
         settled = true;
         this.ws = ws;
         this.ws.on('message', (raw) => this.handleMessage(raw.toString()));
-        this.ws.on('close', () => {
+        this.ws.on('close', (code, reason) => {
+          this.lastDisconnectCode = code;
+          const reasonText = reason?.toString().trim();
+          this.lastDisconnectReason = reasonText ? reasonText : undefined;
           if (this.ws === ws) {
             this.ws = null;
           }
@@ -445,6 +454,8 @@ export class CompanionRuntimeClient {
   }
 
   disconnect(code?: number, reason?: string): void {
+    this.lastDisconnectCode = code;
+    this.lastDisconnectReason = reason;
     if (!this.ws) {
       this.rejectEventWaits(new Error('Disconnected'));
       return;