fix(peer): retain cold-start recovery

Keep persisted Direct targets in the reconnect lifecycle when the first route attempt fails transiently, so later route evidence can revive them without user intervention. Preserve cancellation and permanent-failure boundaries.

Generated-by: Codex (gpt-5.6-sol)

Author: M4n5ter

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

@@ -1018,6 +1018,63 @@ 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('keeps reconnecting through transient startup failures until the Desktop adapter is restored', async () => {
   const first = candidateHarness();
   const replacement = candidateHarness();
@@ -1682,6 +1739,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: {
@@ -1693,7 +1757,7 @@ function peerGuestTarget(
         reachability: testPeerReachability('12D3KooWpeer'),
       },
       rootId: 'a'.repeat(64),
-      access: 'session_guest',
+      ...(access ? { access } : {}),
     },
     credential: 'credential-peer',
   };

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

@@ -853,17 +853,24 @@ class RuntimeHostDesktopManagerImpl implements RuntimeHostDesktopManager {
     initialSignal?: AbortSignal,
   ): Promise<RuntimeHostReconnectLifecycle<DesktopRuntimeHostCandidate>> {
     let starting = true;
+    let initialAttempt = true;
+    const retryInitialFailure =
+      target.target.profile.kind === 'remote' &&
+      target.target.profile.transport.kind === 'libp2p-direct';
     try {
       return await startRuntimeHostReconnectLifecycle({
-        connect: (signal) =>
-          this.connect(
+        connect: (signal) => {
+          const first = initialAttempt;
+          initialAttempt = false;
+          return this.connect(
             target,
-            starting && initialSignal
-              ? AbortSignal.any([signal, initialSignal])
-              : signal,
-            starting ? target.input.profileTarget?.sshInteraction : 'batch',
-            starting ? target.input.onConnectionPhase : undefined,
-          ),
+            signal,
+            first ? target.input.profileTarget?.sshInteraction : 'batch',
+            first ? target.input.onConnectionPhase : undefined,
+          );
+        },
+        retryInitialFailure,
+        ...(initialSignal ? { initialSignal } : {}),
         onReconnectError: (error) => {
           console.warn('[runtime-host] reconnect attempt failed:', error);
         },

docs/architecture/peer-reachability-recovery-plan.md

@@ -318,6 +318,8 @@ charter. Their evidence is adjudicated into this ledger:
 | R11-C1 | correctness | confirmed | Reachability and advertisement anti-entropy now summarize each signed fact as `{ peerId, revision, digest }`, where the digest binds the canonical signed payload. Equal-revision disagreement is rejected during summary comparison instead of remaining silently partitioned between replicas. |
 | R11-C2 | correctness | confirmed | Each WebRTC Relay upgrade now has its own fenced identity and child cancellation token. Removing its Relay retires the active attempt, a replacement can start in the same connection attempt, and a late success is closed unless both its identity and Relay membership are still current. |
 | R12-C1 | correctness | confirmed | The WebRTC Relay-attempt identity now survives through the libp2p dial lifecycle. Candidate replacement retires and closes stale dials, an established connection is admitted only for the exact current attempt, and a late terminal event from an old dial cannot clear its replacement. |
+| R13-C1 | correctness | confirmed | A persisted Direct target now keeps one live reconnect lifecycle when its first connection fails transiently. Route and resume wakeups can therefore recover the same target after a cold-start ordering gap; identity, credential, compatibility, caller cancellation, and other permanent failures still terminate it. `needs_repair` is recoverable state rather than a permanent reconnect verdict. |
+| R13-S1 | simplification | rejected | The active WebRTC attempt is the logical flow identity, while the dial origin maps an external libp2p `ConnectionId` back to that identity. Replacing the explicit relation with phase-dependent map scans does not remove a state owner and weakens the clarity of the remove/re-add Relay ABA fence. |
 
 Only findings that affect the merge bar and have a proportionate root fix enter the
 stack. Narrow constructed paths and low-value polish do not. A local fix triggers a

packages/runtime-host/src/__tests__/reconnecting-connection.test.ts

@@ -508,6 +508,72 @@ test('new reachability evidence wakes an existing reconnect loop without startin
   await lifecycle.close();
 });
 
+test('an initial transient failure keeps a wakeable reconnect lifecycle', async () => {
+  const replacement = connectionHarness('replacement', () => undefined);
+  const waitingForBackoff = deferred();
+  const failures: Error[] = [];
+  let connectCalls = 0;
+  const lifecycle = await startRuntimeHostReconnectLifecycle({
+    retryInitialFailure: true,
+    connect: async () => {
+      connectCalls += 1;
+      if (connectCalls <= 2) throw new Error('the peer is not reachable yet');
+      return replacement.connection;
+    },
+    onReconnectError: (error) => failures.push(error),
+    backoff: {
+      minMs: 30_000,
+      maxMs: 30_000,
+      wait: (_delayMs, signal) =>
+        new Promise<void>((_resolve, reject) => {
+          waitingForBackoff.resolve();
+          const onAbort = () => reject(signal.reason);
+          signal.addEventListener('abort', onAbort, { once: true });
+          if (signal.aborted) onAbort();
+        }),
+    },
+  });
+  try {
+    assert.equal(lifecycle.current, undefined);
+    assert.equal(connectCalls, 2);
+    assert.match(failures[0]?.message ?? '', /not reachable yet/u);
+    await waitingForBackoff.promise;
+
+    lifecycle.wake();
+    assert.equal(await lifecycle.waitForCurrent(), replacement.connection);
+    assert.equal(connectCalls, 3);
+  } finally {
+    await lifecycle.close();
+  }
+});
+
+test('initial retry mode does not outlive caller cancellation', async () => {
+  const controller = new AbortController();
+  const connecting = deferred();
+  const cancelled = new Error('initial connection cancelled');
+  let connectCalls = 0;
+  const starting = startRuntimeHostReconnectLifecycle({
+    retryInitialFailure: true,
+    initialSignal: controller.signal,
+    connect: async (signal): Promise<RuntimeHostConnection> => {
+      connectCalls += 1;
+      connecting.resolve();
+      return new Promise<never>((_resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) onAbort();
+      });
+    },
+    backoff: { minMs: 0, maxMs: 0 },
+  });
+
+  await connecting.promise;
+  controller.abort(cancelled);
+  await assert.rejects(starting, (error: unknown) => error === cancelled);
+  await yieldToEventLoop();
+  assert.equal(connectCalls, 1);
+});
+
 test('reachability discovered during a failed attempt skips the next reconnect delay', async () => {
   const first = connectionHarness('first', () => undefined);
   const replacement = connectionHarness('replacement', () => undefined);

packages/runtime-host/src/client/peer-client.ts

@@ -73,7 +73,7 @@ export interface RuntimeHostPeerRouteResolver {
   subscribeRoutes(peerId: string, listener: () => void): () => void;
 }
 
-export class RuntimeHostPeerReachabilityUnavailableError extends RuntimeHostPermanentReconnectError {
+export class RuntimeHostPeerReachabilityUnavailableError extends Error {
   readonly code = 'peer_reachability_needs_repair';
 
   constructor(peerId: string) {

packages/runtime-host/src/client/reconnect-lifecycle.ts

@@ -77,6 +77,8 @@ export async function startRuntimeHostReconnectLifecycle<
 >(input: {
   readonly initial?: T;
   readonly connect: (signal: AbortSignal) => Promise<T>;
+  readonly retryInitialFailure?: boolean;
+  readonly initialSignal?: AbortSignal;
   readonly onReconnectError?: (error: Error) => void;
   readonly onFatalError?: (error: Error) => void;
   readonly backoff?: RuntimeHostReconnectBackoff;
@@ -99,6 +101,8 @@ class RuntimeHostReconnectLifecycleImpl<T extends RuntimeHostReconnectResource>
   readonly closed: Promise<void>;
   readonly #initial: T | undefined;
   readonly #connect: (signal: AbortSignal) => Promise<T>;
+  readonly #retryInitialFailure: boolean;
+  readonly #initialSignal: AbortSignal | undefined;
   readonly #onReconnectError: ((error: Error) => void) | undefined;
   readonly #onFatalError: ((error: Error) => void) | undefined;
   readonly #minMs: number;
@@ -128,12 +132,16 @@ class RuntimeHostReconnectLifecycleImpl<T extends RuntimeHostReconnectResource>
   constructor(input: {
     readonly initial?: T;
     readonly connect: (signal: AbortSignal) => Promise<T>;
+    readonly retryInitialFailure?: boolean;
+    readonly initialSignal?: AbortSignal;
     readonly onReconnectError?: (error: Error) => void;
     readonly onFatalError?: (error: Error) => void;
     readonly backoff?: RuntimeHostReconnectBackoff;
   }) {
     this.#connect = input.connect;
     this.#initial = input.initial;
+    this.#retryInitialFailure = input.retryInitialFailure ?? false;
+    this.#initialSignal = input.initialSignal;
     this.#onReconnectError = input.onReconnectError;
     this.#onFatalError = input.onFatalError;
     this.#minMs = requireDelay(input.backoff?.minMs ?? DEFAULT_BACKOFF_MIN_MS, 'minMs');
@@ -165,9 +173,30 @@ class RuntimeHostReconnectLifecycleImpl<T extends RuntimeHostReconnectResource>
 
   async start(): Promise<void> {
     try {
-      this.#install(this.#initial ?? (await this.#connect(this.#abort.signal)));
+      if (this.#initial) {
+        this.#install(this.#initial);
+        return;
+      }
+      this.#initialSignal?.throwIfAborted();
+      const signal = this.#initialSignal
+        ? AbortSignal.any([this.#abort.signal, this.#initialSignal])
+        : this.#abort.signal;
+      this.#install(await this.#connect(signal));
     } catch (error) {
-      this.#failPermanently(asError(error));
+      const failure = asError(error);
+      if (
+        this.#retryInitialFailure &&
+        !this.#closed &&
+        !this.#abort.signal.aborted &&
+        !this.#initialSignal?.aborted &&
+        !(failure instanceof RuntimeHostPermanentReconnectError)
+      ) {
+        this.#failureCount += 1;
+        notifyError(this.#onReconnectError, failure);
+        this.#scheduleReconnect();
+        return;
+      }
+      this.#failPermanently(failure);
       throw error;
     }
   }