Uh oh!
There was an error while loading. Please reload this page.
feat(remote-comms): Add kernel incarnation detection protocol - #788
Merged
Conversation
Contributor
Coverage Report
File Coverage |
sirtimid
marked this pull request as ready for review
January 29, 2026 13:58
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
2 tasks
Uh oh!
There was an error while loading. Please reload this page.
sirtimidforce-pushed
the
sirtimid/issue-689-incarnation-detection
branch
from
January 29, 2026 18:52
62c07ec to
606f03fCompareUh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
sirtimidforce-pushed
the
sirtimid/issue-689-incarnation-detection
branch
2 times, most recently
from
February 2, 2026 15:21
34dc2ca to
44b8e91Compare5 tasks
Uh oh!
There was an error while loading. Please reload this page.
sirtimidforce-pushed
the
sirtimid/issue-689-incarnation-detection
branch
from
February 2, 2026 15:33
44b8e91 to
97a32ecCompareUh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
rekmarks
reviewed
Feb 2, 2026
Uh oh!
There was an error while loading. Please reload this page.
sirtimidforce-pushed
the
sirtimid/issue-689-incarnation-detection
branch
from
February 2, 2026 18:57
1bb35d7 to
d516d6cCompareUh oh!
There was an error while loading. Please reload this page.
github-merge-queueBot
pushed a commit
that referenced
this pull request
Feb 3, 2026
…odule (#800) ## Summary - Add `getOrCreateIncarnationId()` to store for unique kernel instance tracking - Add `setRemoteIncarnation()` to peer state manager for tracking remote incarnations - Add handshake module with inbound/outbound handshake functions - Extend `initializeRemoteComms` RPC schema to accept `incarnationId` parameter ## Details This is **part 1 of a 2-PR series** to add incarnation detection support (issue #689). **No behavior change** - This PR adds the capability without using it yet. The `incarnationId` parameter is accepted by the RPC schema but not yet wired through to the transport layer. Part 2 (PR #788) will wire up the handshake protocol and integrate incarnation detection into the reconnection lifecycle. ## Test plan - [x] Unit tests for `getOrCreateIncarnationId()` in store - [x] Unit tests for `setRemoteIncarnation()` in peer state manager - [x] Unit tests for handshake module (inbound/outbound flows) - [x] Unit tests for `initializeRemoteComms` schema accepting `incarnationId` - [x] All existing tests pass 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Medium risk because it introduces new network handshake/timeout behavior and extends persisted state (kernel/peer incarnation IDs), even though the new handshake isn’t yet integrated into the live comms flow. > > **Overview** > Adds incarnation-ID infrastructure to support detecting peer restarts. The kernel store now persists a UUID `incarnationId` via `provideIncarnationId()`, and `PeerStateManager` tracks `remoteIncarnationId` per peer with `setRemoteIncarnation()` returning whether it changed. > > Introduces a new `handshake` module that exchanges `handshake`/`handshakeAck` messages over a `Channel`, with read/write timeouts and validation via `isHandshakeMessage()`. Extends `initializeRemoteComms` RPC params schema to accept an optional `incarnationId` (currently parsed/validated but intentionally not forwarded to the hook), with accompanying unit tests. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 27fde8b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
sirtimidforce-pushed
the
sirtimid/issue-689-incarnation-detection
branch
from
February 3, 2026 10:55
1c79a77 to
848fe35CompareUh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
rekmarks
reviewed
Feb 3, 2026
Uh oh!
There was an error while loading. Please reload this page.
| maxRetryAttempts, | ||
| ); | ||
| // Create handshake dependencies (only if incarnation ID is configured) |
Member
There was a problem hiding this comment.
When would we not configure an incarnation id?
MemberAuthor
There was a problem hiding this comment.
It's optional for unit tests that don't need handshake behavior, in production the kernel always provides an incarnation ID.
Add Handshake and HandshakeAck message types to RemoteMessageBase for kernel incarnation detection protocol. These types will be used to exchange incarnation IDs during connection establishment. Part of #689 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Generate unique incarnation ID (UUID) in Kernel constructor - Store incarnation ID in memory only (not persisted) - Pass incarnation ID through RemoteManager to remote-comms - Update PlatformServices type and RPC handlers to accept incarnationId The incarnation ID is used to detect when a peer has lost its state and reconnected with the same peer ID. Part of #689 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ility" This reverts commit fd0a785.
- Move handshake to connection level in new handshake.ts module - Persist incarnation ID to store via getOrCreateIncarnationId() - Remove incarnationId parameter from RemoteManager (uses store) - Consolidate identity reset logic in Kernel.resetKernelState() - Remove Handshake/HandshakeAck from RemoteMessageBase (handled at transport) The incarnation ID now persists across kernel restarts but resets when storage is cleared, correctly detecting actual state loss vs. restarts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove reconnectionHolder indirection pattern in transport.ts Use definite assignment assertion instead of holder object - Remove duplicate writeWithTimeout from handshake.ts, import from channel-utils - Fix PlatformServicesServer to accept incarnationId parameter - Remove redundant e2e tests for handshake exchange and todo test Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The isHandshakeMessage type guard was only checking for the method property but not validating that params.incarnationId exists and is a string. This could cause runtime errors when a malformed message with the correct method but missing params or incarnationId was received. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The previous implementation used AbortSignal.timeout() which creates an internal timer that continues running even after the read succeeds. This could cause minor memory leaks as the timer and event listener weren't properly cleaned up. Now using AbortController with a manual setTimeout/clearTimeout to ensure the timer is always cleaned up in the finally block. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace the definite assignment assertion (!) with a safer holder pattern that throws a clear error if handleConnectionLoss is called before initialization. This provides runtime safety if code is refactored incorrectly in the future, while keeping TypeScript happy. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unnecessary delay(3000) in incarnation detection test since await will naturally wait for the promise to settle - Add cleanup for the fresh database file created during the test to avoid accumulating test artifacts on disk Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implement the 5 tests that were marked as .todo() due to async handshake flow complexity: - times out after 10 seconds when write hangs - handles timeout errors and triggers connection loss handling - error message includes correct timeout duration - handles multiple concurrent writes with timeout - reuses existing channel when inbound connection arrives during reconnection dial All tests now use proper mocking with makeAbortSignalMock to simulate timeout behavior in a controllable way. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extract the abort handler to a named function so it can be removed in the finally block, preventing a minor memory leak where the event listener would remain registered after the read completes. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
RemoteManager independently gets the incarnation ID from kernelStore, making the Kernel field redundant. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The HandshakeDeps interface defined getRemoteIncarnation but neither performOutboundHandshake nor performInboundHandshake used it. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ient The PlatformServicesClient.initializeRemoteComms method was missing the incarnationId parameter, causing the handshake feature to silently fail in the browser runtime. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ages If JSON.parse returns null, accessing parsed.method throws a TypeError before the ?? 'unknown' fallback can evaluate. Use optional chaining to safely handle null values. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unused getRemoteIncarnation method from PeerStateManager - Change Logger import to type-only import in handshake.ts - Update tests to use getState() instead of removed method Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace file-based database with in-memory database in the incarnation detection e2e test. Each new :memory: SQLite database is a fresh instance that generates a new incarnationId, which is exactly what the test needs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
… handshake Move onRemoteGiveUp callback invocation outside the try-catch block for handshake errors. This ensures callback errors don't incorrectly mark a successful handshake as failed, which would cause unnecessary connection closures and reconnection attempts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…test Address review feedback: check for "Remote connection lost" error message instead of just checking if the response is an Error instance. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Handshake failures during reconnection were incorrectly treated as non-retryable errors, causing immediate give-up even for transient network issues like timeouts. Changed behavior: instead of throwing an error when handshake fails, return null to signal retry. This is consistent with other retryable conditions in tryReconnect. Also fix duplicate closeChannel key in test file. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Assign the fresh database to kernelDatabase2 so that: 1. The afterEach cleanup closes the correct database 2. The old database isn't double-closed Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ing handshake Co-authored-by: Cursor <cursoragent@cursor.com>
- Remove duplicate test cases in handshake.test.ts that were covered by it.each - Add comment explaining when incarnation ID is not configured (tests only) - Add missing incarnationId parameter to NodeJS PlatformServices - Update NodeJS PlatformServices tests for new parameter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
sirtimidforce-pushed
the
sirtimid/issue-689-incarnation-detection
branch
from
February 3, 2026 20:54
cb58190 to
f150b82Comparesirtimid
enabled auto-merge
February 3, 2026 20:59
FUDCo
approved these changes
Feb 3, 2026
Comment on lines
+522
to
+529
| 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'], | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Depends on:#800
Closes#689
Summary
Integrates the handshake protocol for kernel incarnation detection (foundation established in #800). When kernels connect, they exchange incarnation IDs to detect when a peer has lost its state (e.g., storage cleared) but retained the same peer ID.
Key Changes
Handshake Integration (
transport.ts)Incarnation Change Detection
setRemoteIncarnation()returnstrueif incarnation changed from a known previous valueonRemoteGiveUpcallback triggers promise rejection for pending workPromise Rejection Flow
onRemoteGiveUp(peerId)→RemoteManager.#handleRemoteGiveUp()RemoteHandle.rejectPendingRedemptions()for pending URL redemptionsWire-up Changes
Kernel.ts: Initialize incarnation ID and pass toRemoteManagerRemoteManager.ts: Pass incarnation ID to transport layerPlatformServicesClient/Server: Pass incarnation ID through RPCreconnection-lifecycle.ts: Perform handshake during reconnectionFiles Changed
transport.tsreconnection-lifecycle.tsKernel.tsRemoteManager.tsremote-comms.tsPlatformServicesClient.tsPlatformServicesServer.tsTesting
🤖 Generated with Claude Code
Note
High Risk
Introduces a new connection-level handshake and reconnection behavior in
transport.ts, altering how channels are accepted/registered and when remotes are failed, which can affect network compatibility and message delivery under failure/restart scenarios.Overview
Adds an incarnation-ID handshake protocol to remote comms so peers can detect when a connection is re-established to a kernel that lost state (same peerId, new
incarnationId) and proactively fail outstanding work.Plumbs optional
incarnationIdthrough the full initialization stack (KernelStore→RemoteManager→remote-comms→ platform services RPC →initTransport) and updates kernel reset behavior to preserve/clearincarnationIdappropriately.Updates transport lifecycle to handshake before channel registration for outbound, inbound, and reconnection flows; on incarnation change it triggers
onRemoteGiveUpto reject pending promises. Expands unit coverage and adds an e2e test that restarts a peer with fresh storage and asserts the caller seesRemote connection lost.Written by Cursor Bugbot for commit f150b82. This will update automatically on new commits. Configure here.