fix(ocap-kernel): schedule relay reconnect for relays unreachable on startup (#918)

Closes #899

## Summary

When a known relay is down at kernel startup, libp2p starts successfully
but never emits a `connection:close` event for it — so the existing
exponential-backoff reconnection logic never triggers and the relay
remains unreachable until kernel restart.

The fix adds a startup check in `ConnectionFactory#init()` after
`libp2p.start()`: it calls `getConnections()` and schedules reconnection
for any known relay not yet present in the result. This reuses
`#scheduleRelayReconnect` identically to the `connection:close` path, so
both startup failures and post-connection dropouts go through the same
backoff logic (base 5s, max 60s, max 10 attempts).

- Startup check uses `getConnections()` (no awaits introduced, no race
with `connection:close`)
- `#scheduleRelayReconnect`'s deduplication guard
(`#pendingRelayReconnects.has`) ensures a simultaneous
`connection:close` event doesn't double-schedule
- All existing `#stopped` / `#signal.aborted` guards in
`#scheduleRelayReconnect` remain meaningful

## Tests

Four new unit tests cover the startup reconnect path: one relay down,
all relays down, end-to-end recovery, and deduplication with a
simultaneous `connection:close` event. All 24 existing inline libp2p
mocks were updated to include `getConnections` (returning both relays as
connected by default, so no existing test behaviour changes).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes libp2p startup behavior to proactively schedule relay
reconnect attempts based on `getConnections()`, which could increase
initial dial traffic and affects connectivity/timer behavior in a
network-critical component.
> 
> **Overview**
> Ensures relay reconnection backoff also triggers when a known relay is
*unreachable at kernel startup* (i.e., no `connection:close` event is
emitted). After `libp2p.start()`, `ConnectionFactory#init()` now checks
`libp2p.getConnections()` and schedules `#scheduleRelayReconnect` for
any configured relay peerId not currently connected.
> 
> Updates the unit test suite to include `getConnections` in all libp2p
mocks and adds new tests covering startup reconnect scheduling, recovery
when relays come back, and deduplication when a startup reconnect
overlaps with a `connection:close` event.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
7723296. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sirtimid

packages/ocap-kernel/src/remotes/platform/connection-factory.test.ts

@@ -288,6 +288,10 @@ describe('ConnectionFactory', () => {
         },
       ),
       dial: vi.fn(async () => ({})),
+      getConnections: vi.fn(() => [
+        { remotePeer: { toString: () => 'relay1' } },
+        { remotePeer: { toString: () => 'relay2' } },
+      ]),
       getMultiaddrs: vi.fn(() => [
         { toString: () => '/ip4/127.0.0.1/udp/12345/quic-v1/p2p/test-peer-id' },
         { toString: () => '/ip4/127.0.0.1/tcp/9001/ws/p2p/test-peer-id' },
@@ -551,6 +555,10 @@ describe('ConnectionFactory', () => {
         peerId: { toString: () => 'test-peer-id' },
         addEventListener: mockAddEventListener,
         dialProtocol: vi.fn(),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -580,6 +588,10 @@ describe('ConnectionFactory', () => {
         peerId: { toString: () => 'test-peer-id' },
         addEventListener: mockAddEventListener,
         dialProtocol: vi.fn(),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -810,6 +822,10 @@ describe('ConnectionFactory', () => {
           });
           return stream;
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -852,6 +868,10 @@ describe('ConnectionFactory', () => {
             throw new Error('Connection failed again');
           }
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -872,6 +892,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           throw new MuxerClosedError('Muxer closed');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -894,6 +918,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           throw new TooManyStreams('Too many streams');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -928,6 +956,10 @@ describe('ConnectionFactory', () => {
           }
           throw new Error('Should not reach here');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -947,6 +979,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           throw new Error('Final connection error');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -969,6 +1005,10 @@ describe('ConnectionFactory', () => {
           // eslint-disable-next-line @typescript-eslint/only-throw-error
           throw null;
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1030,6 +1070,10 @@ describe('ConnectionFactory', () => {
           const stream = {};
           return stream;
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1052,6 +1096,10 @@ describe('ConnectionFactory', () => {
           attemptCount += 1;
           throw new Error('Non-retryable error');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1113,6 +1161,10 @@ describe('ConnectionFactory', () => {
           }
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1162,6 +1214,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1214,6 +1270,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1254,6 +1314,10 @@ describe('ConnectionFactory', () => {
           await new Promise((resolve) => setTimeout(resolve, 50));
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1280,6 +1344,10 @@ describe('ConnectionFactory', () => {
           dialCount += 1;
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1305,6 +1373,10 @@ describe('ConnectionFactory', () => {
           dialCount += 1;
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1335,6 +1407,10 @@ describe('ConnectionFactory', () => {
           }
           return {};
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1353,6 +1429,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           throw new Error('Dial failed');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1380,6 +1460,10 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => {
           throw new Error('test error');
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1405,6 +1489,10 @@ describe('ConnectionFactory', () => {
           // eslint-disable-next-line @typescript-eslint/only-throw-error
           throw null;
         }),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1430,6 +1518,10 @@ describe('ConnectionFactory', () => {
         peerId: { toString: () => 'test-peer' },
         addEventListener: vi.fn(),
         dialProtocol: vi.fn(),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1483,6 +1575,10 @@ describe('ConnectionFactory', () => {
         peerId: { toString: () => 'test-peer' },
         addEventListener: vi.fn(),
         dialProtocol: vi.fn(),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
       }));
 
@@ -1507,6 +1603,7 @@ describe('ConnectionFactory', () => {
         peerId: { toString: () => 'test-peer' },
         addEventListener: vi.fn(),
         dialProtocol: vi.fn(),
+        dial: vi.fn().mockResolvedValue({}),
         handle: vi.fn(),
         getConnections: vi.fn(() => []),
       }));
@@ -1524,6 +1621,7 @@ describe('ConnectionFactory', () => {
         peerId: { toString: () => 'test-peer' },
         addEventListener: vi.fn(),
         dialProtocol: vi.fn(),
+        dial: vi.fn().mockResolvedValue({}),
         handle: vi.fn(),
         getConnections: vi.fn(() => []),
       }));
@@ -1664,8 +1762,15 @@ describe('ConnectionFactory', () => {
      * Create a libp2p mock that captures event listeners and exposes a dial spy.
      *
      * @param mockDial - The dial mock to use.
+     * @param getConnections - Mock for getConnections; defaults to returning both relays as connected.
      */
-    function setupRelayMock(mockDial: ReturnType<typeof vi.fn>) {
+    function setupRelayMock(
+      mockDial: ReturnType<typeof vi.fn>,
+      getConnections: ReturnType<typeof vi.fn> = vi.fn(() => [
+        { remotePeer: { toString: () => 'relay1' } },
+        { remotePeer: { toString: () => 'relay2' } },
+      ]),
+    ) {
       createLibp2p.mockImplementation(async () => ({
         start: vi.fn(),
         stop: vi.fn(),
@@ -1680,6 +1785,7 @@ describe('ConnectionFactory', () => {
         dialProtocol: vi.fn(async () => ({})),
         handle: vi.fn(),
         dial: mockDial,
+        getConnections,
       }));
     }
 
@@ -1792,6 +1898,10 @@ describe('ConnectionFactory', () => {
         ),
         getMultiaddrs: vi.fn(() => []),
         dialProtocol: vi.fn(async () => ({})),
+        getConnections: vi.fn(() => [
+          { remotePeer: { toString: () => 'relay1' } },
+          { remotePeer: { toString: () => 'relay2' } },
+        ]),
         handle: vi.fn(),
         dial: mockDial,
       }));
@@ -1882,6 +1992,77 @@ describe('ConnectionFactory', () => {
       expect(pendingTimers).toHaveLength(1);
     });
 
+    it('schedules reconnect for relay not connected on startup', async () => {
+      const mockDial = vi.fn().mockResolvedValue({});
+      // relay2 is connected, relay1 is not
+      setupRelayMock(
+        mockDial,
+        vi.fn(() => [{ remotePeer: { toString: () => 'relay2' } }]),
+      );
+
+      factory = await createFactory();
+
+      expect(pendingTimers).toHaveLength(1);
+      expect(mockLoggerLog).toHaveBeenCalledWith(
+        'relay relay1 not connected after startup, scheduling reconnect',
+      );
+    });
+
+    it('schedules reconnect for all relays when none are connected on startup', async () => {
+      const mockDial = vi.fn().mockResolvedValue({});
+      setupRelayMock(
+        mockDial,
+        vi.fn(() => []),
+      );
+
+      factory = await createFactory();
+
+      expect(pendingTimers).toHaveLength(2);
+    });
+
+    it('recovers relay that was down on startup once it comes back up', async () => {
+      const mockDial = vi.fn().mockResolvedValue({});
+      setupRelayMock(
+        mockDial,
+        vi.fn(() => []),
+      );
+
+      factory = await createFactory();
+
+      // Two startup reconnect timers (relay1 and relay2)
+      expect(pendingTimers).toHaveLength(2);
+
+      await runAllTimers();
+
+      expect(mockDial).toHaveBeenCalledTimes(2);
+      expect(mockLoggerLog).toHaveBeenCalledWith(
+        expect.stringContaining('relay relay1 reconnected'),
+      );
+      expect(mockLoggerLog).toHaveBeenCalledWith(
+        expect.stringContaining('relay relay2 reconnected'),
+      );
+    });
+
+    it('does not schedule duplicate startup reconnect when relay also fires connection:close', async () => {
+      const mockDial = vi.fn().mockResolvedValue({});
+      // relay1 not connected on startup
+      setupRelayMock(
+        mockDial,
+        vi.fn(() => [{ remotePeer: { toString: () => 'relay2' } }]),
+      );
+
+      factory = await createFactory();
+
+      // 1 timer from startup reconnect for relay1
+      expect(pendingTimers).toHaveLength(1);
+
+      // connection:close for relay1 fires while startup reconnect is pending
+      fireConnectionClose('relay1');
+
+      // Still just 1 timer — #scheduleRelayReconnect deduplicates
+      expect(pendingTimers).toHaveLength(1);
+    });
+
     it('does not leak timer when stop() runs during in-flight dial', async () => {
       // Dial rejects after stop() has already completed both cleanup passes.
       // The catch block's recursive #reconnectRelay call must not schedule a