fix(ocap-kernel): regenerate incarnationId on resetStorage=true (#950)

## Summary
- Drops \`'incarnationId'\` from \`Kernel.#resetKernelState\`'s
except-list so a state wipe forces a fresh incarnation.
- Adds an e2e regression for the \`resetStorage=true\` path (the
existing #944 test exercises only the fresh-DB path).

## Why
The peer-restart detection added in #948 only works if the sender
signals a new incarnation when its state has been wiped. The except-list
in \`#resetKernelState\` was preserving \`incarnationId\` across
\`resetStorage=true\` resets, so the sender came back signalling the
same incarnation, the receiver's handshake said "no restart",
\`highestReceivedSeq\` stayed put, and the sender's fresh \`seq=1\`
messages were dropped as duplicates.

The browser/extension kernel-worker URL carries \`?reset-storage=true\`
and hits this branch on every offscreen-page reload, so in production
this meant every plugin reload that re-registered a service silently
lost its first message. Repro on metamask-extension chip/agentmask: full
reset → first reload registers cleanly → second reload's PMS
\`registerServiceByRef\` arrives at the matcher with seq=1, matcher logs
\`12D3KooW:: ignoring duplicate message seq=1 (highestReceived=4)\` and
the message disappears.

Confirmed empirically by dumping the matcher's KV after the
second-reload symptom: \`peerIncarnation.<ext-peer-id>\` was equal to
the incarnation the extension was *currently* sending — exactly the case
\`#handleIncarnationChange\` exits early on. The
\`provideIncarnationId\` doc comment already advertised the post-fix
behaviour ("regenerated when storage is cleared (when state is actually
lost)"); the code just wasn't doing it.

## Test plan
- [x] \`yarn workspace @MetaMask/ocap-kernel test\` (2341 passing
locally)
- [x] Production repro on chip/agentmask: full reset, first reload
registers, second reload registers again instead of being dropped
- [ ] CI green, including the new e2e \`detects restart when sender
keeps DB but uses resetStorage=true\`

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes how `resetStorage=true` resets persistent kernel state, which
affects remote-communication handshake/dedup behavior across restarts;
mistakes could cause message loss or unexpected peer identity changes.
> 
> **Overview**
> Fixes the `resetStorage=true` reset path to **regenerate
`incarnationId`** while still preserving network identity keys
(`keySeed`, `peerId`, `ocapURLKey`), so peers can reliably detect a
state wipe and clear stale seq-dedup/c-list state.
> 
> Adds an e2e regression test covering the browser/extension-style
restart where the sender keeps the same DB file but starts with
`resetStorage=true`, ensuring `seq=1` messages are no longer silently
dropped after reloads, and documents the fix in the `CHANGELOG`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c5cb8ea. 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.7 (1M context) <noreply@anthropic.com>

Author: FUDCo

packages/kernel-node-runtime/test/e2e/remote-comms.test.ts

@@ -1118,6 +1118,79 @@ describe.sequential('Remote Communications E2E', () => {
       },
       NETWORK_TIMEOUT * 3,
     );
+
+    it(
+      'detects restart when sender keeps DB but uses resetStorage=true',
+      async () => {
+        // Companion to the test above. The fresh-DB path naturally regenerates
+        // incarnationId (nothing in KV to read). The `resetStorage=true` path
+        // wipes the KV but used to be coded with an except-list that preserved
+        // incarnationId — so the sender came back signaling the same
+        // incarnation, the matcher's handshake said "no restart", and the
+        // sender's fresh seq=1 was dropped against persisted dedup state.
+        // The browser/extension hits this path on every kernel-worker boot
+        // (the offscreen page launches the worker with ?reset-storage=true),
+        // so without this regression a plugin reload silently loses messages.
+        const k2Mnemonic =
+          'legal winner thank year wave sausage worth useful legal winner thank yellow';
+        const opts = {
+          relays: testRelays,
+          reconnectionBaseDelayMs: 100,
+          reconnectionMaxDelayMs: 500,
+          handshakeTimeoutMs: 5_000,
+          writeTimeoutMs: 5_000,
+          ackTimeoutMs: 2_000,
+          maxRetryAttempts: 4,
+        };
+
+        await kernel1.initRemoteComms({ ...opts });
+        await kernel2.initRemoteComms({ ...opts, mnemonic: k2Mnemonic });
+        const aliceURL = await launchVatAndGetURL(
+          kernel1,
+          makeRemoteVatConfig('Alice'),
+        );
+        await launchVatAndGetURL(kernel2, makeRemoteVatConfig('Bob'));
+        const bobRef = getVatRootRef(kernel2, kernelStore2, 'Bob');
+
+        const phase1 = await sendRemoteMessage(
+          kernel2,
+          bobRef,
+          aliceURL,
+          'hello',
+          ['Bob-before-reset'],
+        );
+        expect(phase1).toContain('vat Alice got "hello" from Bob-before-reset');
+
+        // Same delay rationale as in the fresh-DB test above.
+        await delay(150);
+
+        // Restart only the sender, KEEPING its DB but passing
+        // resetStorage=true. This is the path the browser kernel-worker
+        // takes on every offscreen-page reload. Identity keys (keySeed,
+        // peerId, ocapURLKey) must survive so the peer id stays stable;
+        // incarnationId must NOT survive so the matcher's handshake can
+        // detect the wipe.
+        await stopWithTimeout(async () => kernel2.stop(), 3000, 'kernel2.stop');
+        // eslint-disable-next-line require-atomic-updates
+        kernel2 = await restartKernel(dbFilename2, true, testRelays, opts);
+        await launchVatAndGetURL(kernel2, makeRemoteVatConfig('Bob'));
+        // eslint-disable-next-line require-atomic-updates
+        kernelStore2 = makeKernelStore(
+          await makeSQLKernelDatabase({ dbFilename: dbFilename2 }),
+        );
+        const newBobRef = getVatRootRef(kernel2, kernelStore2, 'Bob');
+
+        const phase2 = await sendRemoteMessage(
+          kernel2,
+          newBobRef,
+          aliceURL,
+          'hello',
+          ['Bob-after-reset'],
+        );
+        expect(phase2).toContain('vat Alice got "hello" from Bob-after-reset');
+      },
+      NETWORK_TIMEOUT * 3,
+    );
   });
 
   describe('Promise Rejection on Remote Give-Up', () => {

packages/ocap-kernel/CHANGELOG.md

@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Persist the peer's last-observed incarnation and compare it on every successful handshake; on a detected restart, clear the peer's c-list contributions and reject the promises it was deciding before the new incarnation reuses any erefs
 - Accept liveslots-allocated durable, virtual, and faceted vrefs (e.g. `o+d10/1`, `o+v3/4:0`) in `isVRef` / `insistERef` / `EndpointMessageStruct` validation ([#949](https://github.com/MetaMask/ocap-kernel/pull/949))
   - Previously the regex only matched plain `[op][+-]N`, so any vat using `defineDurableKind` failed outgoing-send validation and persisted-slot reads
+- Regenerate `incarnationId` when `resetStorage=true` clears the rest of kernel state, completing the #948 peer-restart detection on browser/extension kernel reloads ([#950](https://github.com/MetaMask/ocap-kernel/pull/950))
+  - The previous except-list preserved `incarnationId` across `resetStorage` wipes, so a restarted sender signalled the same incarnation it had before the wipe and the matching receiver's handshake decided "no restart" — leaving stale `highestReceivedSeq` in place and silently dropping the sender's fresh `seq=1` messages
 
 ## [0.7.0]
 

packages/ocap-kernel/src/Kernel.ts

@@ -704,8 +704,18 @@ export class Kernel {
   /**
    * Reset the kernel state.
    *
+   * Identity keys (`keySeed`, `peerId`, `ocapURLKey`) are preserved so the
+   * kernel keeps the same network identity across the reset. The
+   * `incarnationId` is deliberately *not* preserved: its whole purpose is
+   * to signal to remote peers that local state has been wiped so they
+   * clear any seq-dedup / c-list bookkeeping for this peer. Preserving it
+   * across a state wipe defeats the peer-restart detection introduced in
+   * #948.
+   *
    * @param options - Options for the reset.
-   * @param options.resetIdentity - If true, also clears identity keys (keySeed, peerId, ocapURLKey, incarnationId).
+   * @param options.resetIdentity - If true, also clears identity keys
+   *   (keySeed, peerId, ocapURLKey). Used when recovering from a
+   *   mnemonic, which is regenerating identity from scratch.
    */
   #resetKernelState({
     resetIdentity = false,
@@ -714,9 +724,11 @@ export class Kernel {
       // Full reset including identity - used when recovering from mnemonic
       this.#kernelStore.reset();
     } else {
-      // Preserve identity keys so network address survives restart
+      // Preserve identity keys so network address survives restart.
+      // `incarnationId` is deliberately omitted: it must be regenerated
+      // so remote peers can detect the state loss via the handshake.
       this.#kernelStore.reset({
-        except: ['keySeed', 'peerId', 'ocapURLKey', 'incarnationId'],
+        except: ['keySeed', 'peerId', 'ocapURLKey'],
       });
     }
   }