feat(companion): add waitForIdle runtime drain helper

src/companion/runtimeClient.test.ts

@@ -643,6 +643,56 @@ describe('CompanionRuntimeClient', () => {
     expect(client.hasPendingWork).toBe(false);
   });
 
+  it('waitForIdle resolves immediately when no work is pending', async () => {
+    const client = new CompanionRuntimeClient({
+      url: 'ws://127.0.0.1:1',
+    });
+
+    await expect(client.waitForIdle()).resolves.toBeUndefined();
+  });
+
+  it('waitForIdle validates pollIntervalMs option', () => {
+    const client = new CompanionRuntimeClient({
+      url: 'ws://127.0.0.1:1',
+    });
+
+    expect(() => client.waitForIdle({ pollIntervalMs: 0 })).toThrow(
+      'pollIntervalMs must be a positive number',
+    );
+  });
+
+  it('waitForIdle resolves after pending event waiters are cleared', async () => {
+    const client = new CompanionRuntimeClient({
+      url: 'ws://127.0.0.1:1',
+    });
+    const pendingWait = client.waitForEvent('agent.stream', { timeoutMs: 10_000 }).catch(() => undefined);
+    expect(client.pendingEventWaitCount).toBe(1);
+
+    const idle = client.waitForIdle({ timeoutMs: 1_000, pollIntervalMs: 5 });
+    setTimeout(() => {
+      client.clearEventSubscriptions();
+    }, 20);
+
+    await expect(idle).resolves.toBeUndefined();
+    await pendingWait;
+    expect(client.pendingEventWaitCount).toBe(0);
+    expect(client.hasPendingWork).toBe(false);
+  });
+
+  it('waitForIdle rejects on timeout while work remains pending', async () => {
+    const client = new CompanionRuntimeClient({
+      url: 'ws://127.0.0.1:1',
+    });
+    const pendingWait = client.waitForEvent('agent.stream', { timeoutMs: 10_000 }).catch(() => undefined);
+
+    await expect(
+      client.waitForIdle({ timeoutMs: 40, pollIntervalMs: 5 }),
+    ).rejects.toThrow('Timed out waiting for runtime idle state');
+
+    client.clearEventSubscriptions();
+    await pendingWait;
+  });
+
   it('connects and performs node registration + capability discovery', async () => {
     if (!LISTEN_ALLOWED) {
       return;