MetaMask · sirtimid · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026
@@ -194,6 +194,7 @@ export class PlatformServicesClient implements PlatformServices {
    * @param options.maxQueue - Maximum number of messages to queue per peer while reconnecting (default: 200).
    * @param remoteMessageHandler - A handler function to receive remote messages.
    * @param onRemoteGiveUp - Optional callback to be called when we give up on a remote.
+   * @param incarnationId - Unique identifier for this kernel instance.
    * @returns A promise that resolves once network access has been established
    *   or rejects if there is some problem doing so.
    */
@@ -202,6 +203,7 @@ export class PlatformServicesClient implements PlatformServices {
     options: RemoteCommsOptions,
     remoteMessageHandler: (from: string, message: string) => Promise<string>,
     onRemoteGiveUp?: (peerId: string) => void,
+    incarnationId?: string,
   ): Promise<void> {
     this.#remoteMessageHandler = remoteMessageHandler;
     this.#remoteGiveUpHandler = onRemoteGiveUp;
@@ -210,6 +212,7 @@ export class PlatformServicesClient implements PlatformServices {
       ...Object.fromEntries(
         Object.entries(options).filter(([, value]) => value !== undefined),
       ),
+      ...(incarnationId !== undefined && { incarnationId }),
     });
   }
 

@@ -406,6 +406,7 @@ describe('PlatformServicesServer', () => {
             { relays },
             expect.any(Function),
             expect.any(Function),
+            undefined,
           );
         });
 
@@ -428,6 +429,7 @@ describe('PlatformServicesServer', () => {
             options,
             expect.any(Function),
             expect.any(Function),
+            undefined,
           );
         });
 

@@ -270,14 +270,13 @@ export class PlatformServicesServer {
    *   connections from other kernels.
    * @param options.maxRetryAttempts - Maximum number of reconnection attempts. 0 = infinite (default).
    * @param options.maxQueue - Maximum number of messages to queue per peer while reconnecting (default: 200).
-   * @param _onRemoteGiveUp - Unused parameter (kept for interface compatibility).
-   *   Remote give-up notifications are sent via RPC instead.
+   * @param incarnationId - This kernel's incarnation ID for handshake protocol.
    * @returns A promise that resolves when network access has been initialized.
    */
   async #initializeRemoteComms(
     keySeed: string,
     options: RemoteCommsOptions,
-    _onRemoteGiveUp?: (peerId: string) => void,
+    incarnationId?: string,
   ): Promise<null> {
     if (this.#sendRemoteMessageFunc) {
       throw Error('remote comms already initialized');
@@ -293,6 +292,7 @@ export class PlatformServicesServer {
       options,
       this.#handleRemoteMessage.bind(this),
       this.#handleRemoteGiveUp.bind(this),
+      incarnationId,
     );
     this.#sendRemoteMessageFunc = sendRemoteMessage;
     this.#stopRemoteCommsFunc = stop;

@@ -4,6 +4,7 @@ import { Kernel, kunser, makeKernelStore } from '@metamask/ocap-kernel';
 import type { KRef } from '@metamask/ocap-kernel';
 import { startRelay } from '@ocap/cli/relay';
 import { delay } from '@ocap/repo-tools/test-utils';
+import { unlink } from 'node:fs/promises';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 
 import { makeTestKernel, runTestVats } from '../helpers/kernel.ts';
@@ -865,6 +866,72 @@ describe.sequential('Remote Communications E2E', () => {
     );
   });
 
+  describe('Incarnation Detection', () => {
+    it(
+      'detects incarnation change when peer restarts with fresh state',
+      async () => {
+        // Initialize with low retry attempts to trigger give-up on incarnation change
+        await kernel1.initRemoteComms({
+          relays: testRelays,
+          maxRetryAttempts: 2,
+        });
+        await kernel2.initRemoteComms({ relays: testRelays });
+
+        const aliceConfig = makeRemoteVatConfig('Alice');
+        const bobConfig = makeRemoteVatConfig('Bob');
+
+        await launchVatAndGetURL(kernel1, aliceConfig);
+        const bobURL = await launchVatAndGetURL(kernel2, bobConfig);
+        const aliceRef = getVatRootRef(kernel1, kernelStore1, 'Alice');
+
+        // Establish connection and exchange handshakes
+        await sendRemoteMessage(kernel1, aliceRef, bobURL, 'hello', ['Alice']);
+
+        // Stop kernel2
+        await kernel2.stop();
+
+        // Simulate state loss by deleting kernel2's database and creating fresh
+        kernelDatabase2.close();
+        const freshDb = await makeSQLKernelDatabase({
+          dbFilename: 'rc-e2e-test-kernel2-fresh.db',
+        });
+
+        try {
+          // Create a completely new kernel (new incarnation ID, no previous state)
+          // eslint-disable-next-line require-atomic-updates
+          kernel2 = await makeTestKernel(freshDb, true);
+          await kernel2.initRemoteComms({ relays: testRelays });
+
+          // Launch Bob again (fresh vat, no previous state)
+          await launchVatAndGetURL(kernel2, bobConfig);
+
+          // Send a message - when the new kernel connects, it will have a different
+          // incarnation ID than before. The handshake will detect this change
+          // and trigger promise rejection for pending work.
+          // The await will naturally wait for the promise to settle - either
+          // succeeding (unexpected) or failing due to incarnation change detection.
+          const result = await kernel1.queueMessage(
+            aliceRef,
+            'sendRemoteMessage',
+            [bobURL, 'hello', ['Alice']],
+          );
+          const response = kunser(result);
+
+          // The message should fail because incarnation changed
+          // Either due to promise rejection or remote state being lost
+          expect(response).toBeInstanceOf(Error);
+        } finally {
+          freshDb.close();
+          // Clean up the fresh database file
+          await unlink('rc-e2e-test-kernel2-fresh.db').catch(() => {
+            // Ignore errors if file doesn't exist
+          });
+        }
+      },
+      NETWORK_TIMEOUT * 3,
+    );
+  });
+
   describe('Promise Rejection on Remote Give-Up', () => {
     it(
       'rejects promises when remote connection is lost after max retries',

@@ -106,15 +106,11 @@ export class Kernel {
     }
 
     if (options.resetStorage) {
-      this.#resetKernelState();
       // If mnemonic is provided with resetStorage, also clear identity
       // to allow recovery with the new mnemonic
-      if (options.mnemonic) {
-        this.#kernelStore.kv.delete('keySeed');
-        this.#kernelStore.kv.delete('peerId');
-        this.#kernelStore.kv.delete('ocapURLKey');
-      }
+      this.#resetKernelState({ resetIdentity: Boolean(options.mnemonic) });
     }
+
     this.#kernelQueue = new KernelQueue(
       this.#kernelStore,
       async (vatId, reason) => this.#vatManager.terminateVat(vatId, reason),
@@ -516,12 +512,22 @@ export class Kernel {
 
   /**
    * Reset the kernel state.
-   */
-  #resetKernelState(): void {
-    this.#kernelStore.reset({
-      // XXX special case hack so that network address survives restart when testing
-      except: ['keySeed', 'peerId', 'ocapURLKey'],
-    });
+   *
+   * @param options - Options for the reset.
+   * @param options.resetIdentity - If true, also clears identity keys (keySeed, peerId, ocapURLKey, incarnationId).
+   */
+  #resetKernelState({
+    resetIdentity = false,
+  }: { resetIdentity?: boolean } = {}): void {
+    if (resetIdentity) {
+      // Full reset including identity - used when recovering from mnemonic
+      this.#kernelStore.reset();
+    } else {
+      // Preserve identity keys so network address survives restart
+      this.#kernelStore.reset({
+        except: ['keySeed', 'peerId', 'ocapURLKey', 'incarnationId'],
+      });
+    }
   }
 
   /**

@@ -80,6 +80,7 @@ describe('RemoteManager', () => {
         logger,
         undefined,
         expect.any(Function),
+        kernelStore.getOrCreateIncarnationId(),
       );
     });
 
@@ -102,10 +103,12 @@ describe('RemoteManager', () => {
           relays: ['relay1', 'relay2'],
           maxRetryAttempts: 5,
           maxQueue: 100,
+          mnemonic: undefined,
         },
         logger,
         undefined,
         expect.any(Function),
+        kernelStore.getOrCreateIncarnationId(),
       );
     });
 
@@ -133,6 +136,7 @@ describe('RemoteManager', () => {
         logger,
         keySeed,
         expect.any(Function),
+        kernelStore.getOrCreateIncarnationId(),
       );
     });
 

@@ -50,6 +50,12 @@ export class RemoteManager {
   /** Optional mnemonic for seed derivation */
   readonly #mnemonic: string | undefined;
 
+  /**
+   * Unique identifier for this kernel instance.
+   * Used to detect when a remote peer has lost its state and reconnected.
+   */
+  readonly #incarnationId: string;
+
   /** Remote communications interface */
   #remoteComms: RemoteComms | undefined;
 
@@ -81,6 +87,8 @@ export class RemoteManager {
     this.#logger = logger;
     this.#keySeed = keySeed;
     this.#mnemonic = mnemonic;
+    // Get incarnation ID from store - it's persisted so it survives restarts
+    this.#incarnationId = kernelStore.getOrCreateIncarnationId();
   }
 
   /**
@@ -153,6 +161,7 @@ export class RemoteManager {
       this.#logger,
       this.#keySeed,
       this.#handleRemoteGiveUp.bind(this),
+      this.#incarnationId,
     );
 
     // Restore all remotes that were previously established

@@ -143,6 +143,7 @@ describe('remote-comms', () => {
         }),
         mockRemoteMessageHandler,
         undefined, // onRemoteGiveUp
+        undefined, // incarnationId
       );
     });
 
@@ -165,6 +166,7 @@ describe('remote-comms', () => {
         }),
         mockRemoteMessageHandler,
         undefined,
+        undefined, // incarnationId
       );
     });
 
@@ -184,6 +186,28 @@ describe('remote-comms', () => {
         expect.any(Object),
         mockRemoteMessageHandler,
         onRemoteGiveUp,
+        undefined, // incarnationId
+      );
+    });
+
+    it('passes incarnationId to platformServices', async () => {
+      const incarnationId = 'test-incarnation-id';
+      await initRemoteComms(
+        mockKernelStore,
+        mockPlatformServices,
+        mockRemoteMessageHandler,
+        {},
+        undefined, // logger
+        undefined, // keySeed
+        undefined, // onRemoteGiveUp
+        incarnationId,
+      );
+      expect(mockPlatformServices.initializeRemoteComms).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Object),
+        mockRemoteMessageHandler,
+        undefined,
+        incarnationId,
       );
     });
 

@@ -104,6 +104,7 @@ export function getKnownRelays(kv: KVStore): string[] {
  * @param logger - The logger to use.
  * @param keySeed - Optional seed for libp2p key generation.
  * @param onRemoteGiveUp - Optional callback to be called when we give up on a remote.
+ * @param incarnationId - Unique identifier for this kernel instance.
  *
  * @returns the initialized remote comms object.
  */
@@ -115,6 +116,7 @@ export async function initRemoteComms(
   logger?: Logger,
   keySeed?: string,
   onRemoteGiveUp?: OnRemoteGiveUp,
+  incarnationId?: string,
 ): Promise<RemoteComms> {
   let peerId: string;
   let ocapURLKey: Uint8Array;
@@ -167,6 +169,7 @@ export async function initRemoteComms(
     { ...options, relays: knownRelays },
     remoteMessageHandler,
     onRemoteGiveUp,
+    incarnationId,
   );
 
   /**