Summary

• Problem: a stale node WebSocket close could unregister or mark disconnected state for a node that had already reconnected with the same node id.
• Why it matters: gateway node presence, node.list, and node invokes can diverge during reconnect races, making a live node appear disconnected until another presence update arrives.
• What changed: NodeRegistry now scopes pending invokes and stale unregister cleanup by connId; node.invoke.result matches pending work by nodeId + connId; WebSocket close handling only writes node disconnect presence when the closing socket still owns the current node session.
• What did NOT change (scope boundary): no protocol schema changes, no node pairing changes, and no reconnect policy changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes N/A
• Related N/A
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: stale node socket close after reconnect should not clear the new live node session, should not complete new-connection pending invokes from the old connection, and should not broadcast a node presence disconnect for the replacement session.
• Real environment tested: local macOS workspace with Node/pnpm test runner plus a real Gateway WebSocket reconnect harness using a paired node-role client.
• Exact steps or command run after this patch: pnpm test src/gateway/node-registry.test.ts src/gateway/gateway-misc.test.ts src/gateway/server/ws-connection.test.ts -- --reporter=verbose; pnpm check:changed; one-off pnpm exec tsx live Gateway harness that starts a loopback Gateway, pairs operator and node devices, connects the same node id twice, closes the old socket late, then verifies node.list, node.invoke, and system-presence.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): targeted tests passed: 3 files, 40 tests; pnpm check:changed passed core/coreTests typecheck, lint, and guards; live Gateway reconnect harness passed with copied terminal output:

LIVE_PROOF_PASS pr=78351 sha=5e74a09d24ba501c821b68390a1135cc4f0f70fc
gateway_url=ws://127.0.0.1:49817
node_id=c628f148a45664d0a21cf434846fed9e68b115e4c2eee4eb3a2b42d9d20931d9
before_reconnect.connected=true commands=["device.info"]
after_reconnect.connected=true commands=["device.info"]
after_old_close.connected=true commands=["device.info"]
invoke.payload.handledBy=new
presence.reason=connect presence.instanceId=c628f148a45664d0a21cf434846fed9e68b115e4c2eee4eb3a2b42d9d20931d9
invoke_requests.old=0 invoke_requests.new=1

• Observed result after fix: stale unregister returns null, keeps the reconnected session, rejects only the old connection's pending invokes, ignores mismatched invoke results, skips node presence disconnect broadcast for stale sockets, and the live replacement node still handles node.invoke after the old socket closes.
• What was not tested: physical mobile/desktop app binary reconnect. A live loopback Gateway WebSocket reconnect with a paired node-role client was tested.
• Before evidence (optional but encouraged): the added node-registry regression fails on the old implementation because unregister(oldConnId) deletes the current nodesById entry.

Root Cause (if applicable)

• Root cause: NodeRegistry.unregister(connId) resolved the old connection to a nodeId and then cleaned nodesById, pending invokes, and close-side node state by nodeId without verifying that the closing connection still owned the current node session.
• Missing detection / guardrail: no regression test covered reconnecting the same node id before the old socket close event ran.
• Contributing context (if known): node sessions are keyed by nodeId, while WebSocket lifecycle events are keyed by connId.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/node-registry.test.ts; src/gateway/server/ws-connection.test.ts.
• Scenario the test should lock in: old/new connections with the same node id, stale old close, current session preserved, stale invoke result rejected, old pending invoke disconnected, and stale close presence disconnect skipped.
• Why this is the smallest reliable guardrail: it exercises the registry and close-handler seams directly without starting a full Gateway process.
• Existing test that already covers this (if any): none before this PR.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

A reconnected node should no longer briefly appear disconnected or lose pending node invoke state because an older socket closed late.

Diagram (if applicable)

Before:
old socket close -> unregister(nodeId) -> deletes new session / broadcasts disconnect

After:
old socket close -> unregister(connId) -> stale close returns null -> new session remains live

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local development workspace
• Runtime/container: Node 22+ via repo pnpm scripts
• Model/provider: N/A
• Integration/channel (if any): Gateway node WebSocket lifecycle
• Relevant config (redacted): default local test configuration; live harness used an isolated temporary OPENCLAW_STATE_DIR and loopback token auth

Steps

1. Register an old node connection for node-1 and start a node invoke.
2. Register a new node connection for the same node-1.
3. Deliver a result from the wrong connId, then close the old connection.
4. Exercise the WebSocket close handler where nodeRegistry.unregister(connId) returns null for a stale node socket.
5. In the live harness, start a real loopback Gateway, pair operator and node devices, connect the same node id twice, close the old socket, then verify the replacement node remains connected and handles node.invoke.

Expected

• The new session remains registered.
• The mismatched invoke result is ignored.
• The old pending invoke is rejected on old socket close.
• The stale close does not write or broadcast node presence disconnect.
• The replacement live node remains visible in node.list, keeps connected presence, and handles node.invoke after the old socket closes.

Actual

• Matches expected in the new regression tests and in the live Gateway reconnect harness.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: targeted registry reconnect race, stale invoke result rejection, old pending invoke disconnect cleanup, stale close presence disconnect skip, and live Gateway WebSocket reconnect where the replacement node remains connected and handles node.invoke after the stale old socket closes.
• Edge cases checked: node.invoke.result still treats unknown/late invoke ids as ignored success through gateway-misc.test.ts; current close cleanup remains gated on unregister returning the active node id.
• What you did not verify: reconnect with a physical mobile/desktop app binary.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: close-handler ordering changes could affect non-node clients.
  • Mitigation: disconnect presence still runs for non-node clients with a presenceKey; the new guard only suppresses node disconnect presence when unregister(connId) reports a stale close.

Considered and deferred

• src/gateway/server/ws-connection.test.ts:321 [BOT-NIT]: New test repeats the local socket harness pattern already used in this file. Extracting a helper would be cleanup, not a correctness fix, and would broaden this commit.