feat(peer): recover live routes in one connection attempt

apps/desktop/src/main/__tests__/runtime-host-collaboration-ipc-main.test.ts

@@ -129,11 +129,7 @@ test('requires plaintext confirmation and reports the issued invitation routes',
       name: 'Peer Lab',
       transport: {
         kind: 'libp2p-direct',
-        peerId: '12D3KooWpeer',
-        routeHints: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
-        coordinationRelays: [
-          '/dns4/relay.example/udp/443/quic-v1/p2p/12D3KooWrelay',
-        ],
+        reachability: peerReachability(),
       },
     }),
   );
@@ -151,6 +147,22 @@ test('requires plaintext confirmation and reports the issued invitation routes',
   );
 });
 
+function peerReachability() {
+  return {
+    lease: {
+      version: 1 as const,
+      peerId: '12D3KooWpeer',
+      revision: 1,
+      issuedAt: 1,
+      expiresAt: 2,
+      directRoutes: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
+      coordinationRoutes: ['/dns4/relay.example/udp/443/quic-v1/p2p/12D3KooWrelay'],
+    },
+    publicKey: Buffer.from('public').toString('base64url'),
+    signature: Buffer.from('signature').toString('base64url'),
+  };
+}
+
 test('treats an unavailable collaboration authority as an empty background inbox', async () => {
   const handlers = new Map<string, IpcHandler>();
   registerRuntimeHostCollaborationIpc(

apps/desktop/src/main/__tests__/runtime-host-desktop-manager.test.ts

@@ -22,6 +22,7 @@ import test from 'node:test';
 import type { BotIncomingMessage } from '@maka/runtime/bots';
 import {
   RuntimeHostOperationError,
+  RuntimeHostPermanentReconnectError,
   RuntimeHostRequestInterruptedError,
   type RuntimeHostSpawnedProcess,
 } from '@maka/runtime-host/client';
@@ -1018,6 +1019,88 @@ test('keeps Local explicitly usable without routing default work away from an un
   await manager.close();
 });
 
+test('keeps an initially unavailable Direct target live and wakes it on new routes', async () => {
+  const local = candidateHarness();
+  const remote = candidateHarness({ hostId: 'a'.repeat(64), ownership: 'external' });
+  let starts = 0;
+  let routeListener: (() => void) | undefined;
+  let reportBackoff!: () => void;
+  const waitingForBackoff = new Promise<void>((resolve) => {
+    reportBackoff = resolve;
+  });
+  const manager = await startRuntimeHostDesktopManager(
+    {
+      peerClient: {
+        subscribeRoutes: (peerId: string, listener: () => void) => {
+          assert.equal(peerId, '12D3KooWpeer');
+          routeListener = listener;
+          return () => undefined;
+        },
+      },
+    } as DesktopRuntimeHostCandidateStartInput,
+    {
+      startCandidate: async () => {
+        starts += 1;
+        if (starts === 1) return ready(local.candidate);
+        if (starts <= 3) return { kind: 'failed', reason: 'host_unresponsive' };
+        return ready(remote.candidate);
+      },
+      reconnectBackoff: {
+        minMs: 30_000,
+        maxMs: 30_000,
+        wait: (_delayMs, signal) =>
+          new Promise<void>((_resolve, reject) => {
+            reportBackoff();
+            const onAbort = () => reject(signal.reason);
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted) onAbort();
+          }),
+      },
+    },
+  );
+
+  await manager.enable(peerTarget('office'));
+  await waitingForBackoff;
+  assert.equal(
+    manager.entries().find((state) => state.target.profile.id === 'office')?.readiness,
+    'reconnecting',
+  );
+  assert.equal(manager.current('office')?.readiness, 'reconnecting');
+  assert.equal(manager.current('office')?.candidate, undefined);
+  assert.ok(routeListener);
+
+  routeListener();
+  await manager.waitUntilReady('office');
+  assert.equal(manager.current('office')?.candidate, remote.candidate);
+  assert.equal(starts, 4);
+  await manager.close();
+});
+
+test('does not activate a Direct target whose immediate retry fails permanently', async () => {
+  const local = candidateHarness();
+  const permanent = new RuntimeHostPermanentReconnectError('credential rejected');
+  let starts = 0;
+  const manager = await startRuntimeHostDesktopManager(
+    {} as DesktopRuntimeHostCandidateStartInput,
+    {
+      startCandidate: async () => {
+        starts += 1;
+        if (starts === 1) return ready(local.candidate);
+        if (starts === 2) throw new Error('route is temporarily unavailable');
+        throw permanent;
+      },
+    },
+  );
+
+  await assert.rejects(manager.enable(peerTarget('office')), (error: unknown) => error === permanent);
+  assert.equal(starts, 3);
+  assert.equal(manager.current('office'), undefined);
+  const state = manager.entries().find((entry) => entry.target.profile.id === 'office');
+  assert.equal(state?.readiness, 'unavailable');
+  if (state?.readiness === 'unavailable') assert.equal(state.error, permanent);
+  await manager.close();
+});
+
 test('keeps reconnecting through transient startup failures until the Desktop adapter is restored', async () => {
   const first = candidateHarness();
   const replacement = candidateHarness();
@@ -1682,6 +1765,13 @@ function remoteTarget(
 
 function peerGuestTarget(
   id: string,
+): NonNullable<DesktopRuntimeHostCandidateStartInput['profileTarget']> {
+  return peerTarget(id, 'session_guest');
+}
+
+function peerTarget(
+  id: string,
+  access?: 'session_guest',
 ): NonNullable<DesktopRuntimeHostCandidateStartInput['profileTarget']> {
   return {
     profile: {
@@ -1690,13 +1780,27 @@ function peerGuestTarget(
       kind: 'remote',
       transport: {
         kind: 'libp2p-direct',
-        peerId: '12D3KooWpeer',
-        routeHints: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
-        coordinationRelays: [],
+        reachability: testPeerReachability('12D3KooWpeer'),
       },
       rootId: 'a'.repeat(64),
-      access: 'session_guest',
+      ...(access ? { access } : {}),
     },
     credential: 'credential-peer',
   };
 }
+
+function testPeerReachability(peerId: string) {
+  return {
+    lease: {
+      version: 1 as const,
+      peerId,
+      revision: 1,
+      issuedAt: 1,
+      expiresAt: 2,
+      directRoutes: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
+      coordinationRoutes: [],
+    },
+    publicKey: Buffer.from('public').toString('base64url'),
+    signature: Buffer.from('signature').toString('base64url'),
+  };
+}

apps/desktop/src/main/__tests__/runtime-host-guest-session-mounts.test.ts

@@ -19,7 +19,10 @@
 
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import type { ResolvedRuntimeHostProfile } from '@maka/runtime-host/client';
+import {
+  RuntimeHostPermanentReconnectError,
+  type ResolvedRuntimeHostProfile,
+} from '@maka/runtime-host/client';
 import {
   encodeCollaborationInvitationCode,
   type HostPeerEndpoint,
@@ -106,9 +109,7 @@ test('persists authenticated route rotation for reconnect and restart', async ()
         target.profile.kind === 'remote' ? target.profile.transport : undefined,
         {
           kind: 'libp2p-direct',
-          peerId: '12D3KooWpeer',
-          routeHints: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
-          coordinationRelays: ['/memory/stale-relay'],
+          reachability: guestPeerReachability(),
         },
       );
       assert.ok(onPeerEndpoint);
@@ -118,19 +119,12 @@ test('persists authenticated route rotation for reconnect and restart', async ()
 
   const imported = await first.importInvitation(peerInvitation('guest-routes'), false, 'routes');
   assert.equal(imported.kind, 'connected');
-  observePeerEndpoint({
-    lease: {
-      version: 1,
-      peerId: '12D3KooWpeer',
-      revision: 2,
-      issuedAt: 1,
-      expiresAt: 2,
-      directRoutes: ['/ip4/198.51.100.2/udp/42000/quic-v1'],
-      coordinationRoutes: ['/memory/fresh-relay'],
-    },
-    publicKey: 'AA',
-    signature: 'AA',
-  });
+  const rotated = guestPeerReachability(
+    2,
+    ['/ip4/198.51.100.2/udp/42000/quic-v1'],
+    ['/memory/fresh-relay'],
+  );
+  observePeerEndpoint(rotated);
   await first.close();
 
   let restarted!: ReturnType<typeof service>;
@@ -141,9 +135,7 @@ test('persists authenticated route rotation for reconnect and restart', async ()
   const target = await restartedTarget;
   assert.deepEqual(target.profile.kind === 'remote' ? target.profile.transport : undefined, {
     kind: 'libp2p-direct',
-    peerId: '12D3KooWpeer',
-    routeHints: ['/ip4/198.51.100.2/udp/42000/quic-v1'],
-    coordinationRelays: ['/memory/fresh-relay'],
+    reachability: rotated,
   });
   await restarted.close();
 });
@@ -153,7 +145,9 @@ test('removes failed activation desire instead of creating recoverable profile s
   const unmounted: string[] = [];
   const mounts = service(store, {
     mount: async () => {
-      throw Object.assign(new Error('route missing'), { code: 'direct_path_unavailable' });
+      throw Object.assign(new Error('route missing'), {
+        code: 'peer_reachability_needs_repair',
+      });
     },
     unmount: async (mountId) => {
       unmounted.push(mountId);
@@ -166,6 +160,34 @@ test('removes failed activation desire instead of creating recoverable profile s
   assert.equal(unmounted.length, 1);
 });
 
+test('does not retry a startup mount whose reachability recovery is exhausted', async () => {
+  const store = memoryStore();
+  await store.write([retainedMount('shared-needs-repair')]);
+  let attempts = 0;
+  let waits = 0;
+  let reportFailure!: () => void;
+  const failureReported = new Promise<void>((resolve) => {
+    reportFailure = resolve;
+  });
+  const mounts = service(store, {
+    mount: async () => {
+      attempts += 1;
+      throw new RuntimeHostPermanentReconnectError('reachability recovery exhausted');
+    },
+    wait: async () => {
+      waits += 1;
+    },
+    onError: () => reportFailure(),
+  });
+
+  await mounts.start();
+  await failureReported;
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(attempts, 1);
+  assert.equal(waits, 0);
+  await mounts.close();
+});
+
 test('settles admitted finalization before committing unmount desire', async () => {
   const store = memoryStore();
   let started!: () => void;
@@ -417,14 +439,17 @@ function service(
     readonly mount?: Parameters<typeof createDesktopGuestSessionMountService>[0]['mount'];
     readonly finalizeAccess?: Parameters<typeof createDesktopGuestSessionMountService>[0]['finalizeAccess'];
     readonly unmount?: Parameters<typeof createDesktopGuestSessionMountService>[0]['unmount'];
+    readonly wait?: Parameters<typeof createDesktopGuestSessionMountService>[0]['wait'];
+    readonly onError?: Parameters<typeof createDesktopGuestSessionMountService>[0]['onError'];
   } = {},
 ) {
   return createDesktopGuestSessionMountService({
     store,
     mount: overrides.mount ?? (async () => undefined),
     finalizeAccess: overrides.finalizeAccess ?? (async () => undefined),
     unmount: overrides.unmount ?? (async () => undefined),
-    onError: () => undefined,
+    ...(overrides.wait ? { wait: overrides.wait } : {}),
+    onError: overrides.onError ?? (() => undefined),
   });
 }
 
@@ -463,14 +488,32 @@ function peerInvitation(credential: string): string {
       name: 'Shared Host',
       transport: {
         kind: 'libp2p-direct',
-        peerId: '12D3KooWpeer',
-        routeHints: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
-        coordinationRelays: ['/memory/stale-relay'],
+        reachability: guestPeerReachability(),
       },
     },
   });
 }
 
+function guestPeerReachability(
+  revision = 1,
+  directRoutes: readonly string[] = ['/ip4/192.0.2.1/udp/41000/quic-v1'],
+  coordinationRoutes: readonly string[] = ['/memory/stale-relay'],
+) {
+  return {
+    lease: {
+      version: 1 as const,
+      peerId: '12D3KooWpeer',
+      revision,
+      issuedAt: 1,
+      expiresAt: 2,
+      directRoutes,
+      coordinationRoutes,
+    },
+    publicKey: Buffer.from('public').toString('base64url'),
+    signature: Buffer.from('signature').toString('base64url'),
+  };
+}
+
 function retainedMount(mountId: string): GuestSessionMount {
   return {
     mountId,

apps/desktop/src/main/__tests__/runtime-host-local-remote-access.test.ts

@@ -143,12 +143,7 @@ test('enabling remote access hands the same root to one managed service before D
   assert.deepEqual(decodeRuntimeHostOwnerConnectionCode(result.connectionCode), {
     name: decodeRuntimeHostOwnerConnectionCode(result.connectionCode).name,
     rootId: 'a'.repeat(64),
-    transport: {
-      kind: 'libp2p-direct',
-      peerId: livePeer.lease.peerId,
-      routeHints: livePeer.lease.directRoutes,
-      coordinationRelays: livePeer.lease.coordinationRoutes,
-    },
+    transport: { kind: 'libp2p-direct', reachability: livePeer },
     credential: 'pending-credential',
   });
   const lifecycle = JSON.parse(
@@ -169,12 +164,12 @@ test('shares the running Local Host endpoint instead of its persisted startup ro
   await writeManagedLifecycle(clientDataRoot, rootPath, rootId);
   const configuredPeer = {
     peerId: '12D3KooWpeer',
-    routeHints: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
+    routeHints: [],
     coordinationRelays: [],
   };
   const livePeer = peerReachability(
     configuredPeer.peerId,
-    configuredPeer.routeHints,
+    ['/ip4/192.0.2.1/udp/41000/quic-v1'],
     ['/dns4/relay.example/udp/443/quic-v1/p2p/12D3KooWrelay'],
   );
   const service = createDesktopLocalRuntimeHostRemoteAccess({
@@ -219,12 +214,7 @@ test('shares the running Local Host endpoint instead of its persisted startup ro
   const target = await service.createCollaborationConnectionTarget();
   assert.deepEqual(target, {
     name: target.name,
-    transport: {
-      kind: 'libp2p-direct',
-      peerId: livePeer.lease.peerId,
-      routeHints: livePeer.lease.directRoutes,
-      coordinationRelays: livePeer.lease.coordinationRoutes,
-    },
+    transport: { kind: 'libp2p-direct', reachability: livePeer },
   });
 });