fix(node): trust gateway session attribution only

[vincentkoc]

What Problem This Solves

Fixes an issue where the Windows node could trust nested caller session attribution or dispatch node invocation traffic before it knew whether the connected Gateway supported authoritative session envelopes.

Why This Change Was Made

The Windows node publishes the generic session-envelope feature after handshake, correlates the feature request response, queues invoke/input/cancel traffic in wire order during negotiation, and uses the legacy nested session key only after an explicit old-Gateway unknown-method response. Timeout and unrelated failures remain authoritative and fail closed.

This mirrors the OpenClaw node-host contract tracked by openclaw/openclaw#116528 without introducing passport, certificate, key-store, IdP, SCIM, OAuth, or public identity surfaces.

User Impact

Windows node users retain compatibility with older Gateways while preventing caller-supplied nested data from overriding authoritative Gateway attribution on supported or indeterminate connections.

Evidence

• focused WindowsNodeClient, capability, and exec-approval validation tests added;
• structured autoreview completed with no actionable findings;
• native Windows build and test proof is delegated to this draft PR's GitHub Actions because .NET is not installed in the authoring environment.

[clawsweeper]

Codex review: found issues before merge. Reviewed August 2, 2026, 1:57 PM ET / 17:57 UTC.

ClawSweeper review

What this changes

The PR adds a post-handshake Gateway feature negotiation so Windows-node invocations prefer Gateway-stamped session envelopes and only use nested session keys with explicitly legacy Gateways.

Merge readiness

⛔ Blocked until real behavior proof is added - 9 items remain

This member-authored draft is still necessary, but it is not safe to merge yet. The unchanged head retains all three previously reported P1 protocol regressions: it misses common legacy unknown-method errors, discards trusted request-envelope session attribution, and delays event cancellation behind capability negotiation.

Priority: P1
Reviewed head: 4a137f6b10131932232f341b077c1edf8c606fa7

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The proposed trust-boundary direction is useful, but three high-priority protocol defects and missing real behavior proof make the current head not merge-ready.
Proof confidence	🧂 unranked krab (1/6)	Needs real behavior proof before merge: The PR body lists focused tests and GitHub Actions, but it has no current-head after-fix Gateway, MCP, terminal, or redacted runtime proof. Add proof after the P1 corrections and redact tokens, endpoints, and device identifiers; updating the PR body should trigger a fresh review, or a maintainer can request @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🧂 unranked krab (1/6)	3 actionable review findings remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The PR body lists focused tests and GitHub Actions, but it has no current-head after-fix Gateway, MCP, terminal, or redacted runtime proof. Add proof after the P1 corrections and redact tokens, endpoints, and device identifiers; updating the PR body should trigger a fresh review, or a maintainer can request @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	6 items	Legacy fallback remains too narrow: The PR only recognizes an object-shaped error with code INVALID_REQUEST and an exact-case message substring. A flat string error such as "unknown method: ..." leaves older Gateways in authoritative mode instead of reaching the advertised legacy fallback. Trusted request-envelope attribution is discarded: The direct request transport constructs NodeInvokeRequest without copying params.sessionKey, despite the established Gateway contract and the collaborator review identifying that envelope field as Gateway-stamped. Cancellation waits for negotiation: Queued event traffic always awaits the feature-negotiation task before dispatching either invocation or cancellation. A cancel received during the five-second negotiation window cannot cancel an invocation promptly.
Findings	3 actionable findings	[P1] Accept legacy unknown-method response variants [P1] Preserve trusted request-envelope session attribution [P1] Dispatch cancellation before attribution negotiation
Security	None	None.

How this fits together

The Windows node receives Gateway WebSocket events and requests, extracts session correlation, then dispatches local capabilities such as command execution. This change inserts feature negotiation between connection handshake and invocation dispatch so the node can decide which session attribution source to trust.

flowchart LR
  A[Gateway connection] --> B[Handshake succeeds]
  B --> C[Session-envelope feature negotiation]
  C --> D[Gateway invoke or cancel traffic]
  D --> E[Trusted session attribution]
  E --> F[Local node capability]
  F --> G[Gateway result or cancellation]

Loading

Before merge

• Accept legacy unknown-method response variants (P1) - Older Gateways can return a flat error string or change the casing of unknown method. This classifier only accepts an object with INVALID_REQUEST and an exact-case message, so the intended legacy mode is unreachable and compatible invocation traffic fails closed.
• Preserve trusted request-envelope session attribution (P1) - The request transport’s params.sessionKey is Gateway-stamped, but this branch drops it entirely while creating NodeInvokeRequest. Only nested caller-controlled arguments should be ignored; otherwise approval and execution lose trusted session correlation.
• Dispatch cancellation before attribution negotiation (P1) - Every queued event awaits the feature-negotiation task before switching on its kind. A cancellation received during negotiation waits up to the timeout instead of cancelling the already-started invocation, which can make cancellation ineffective.
• Resolve merge risk (P1) - Older Gateways that return flat or case-variant unknown-method errors will never enter compatibility mode, so invocation traffic can fail closed instead of using the intended legacy path.
• Resolve merge risk (P1) - Dropping Gateway-stamped request-envelope session attribution breaks the correlation used by approval and command-execution flows even when the Gateway supplied trusted metadata.
• Resolve merge risk (P1) - A cancellation event can sit behind up to five seconds of protocol negotiation, making cancellation ineffective for short-running or time-sensitive invocations.
• Complete next step (P2) - The defects are concrete, but this is a member-authored draft with explicit collaborator review and a missing real-behavior merge gate, so it should remain in maintainer-led review rather than enter an automated repair lane.
• Improve patch quality - Correct the three P1 transport behaviors and add regression coverage for the concrete legacy/error, request-envelope, and cancellation sequences.
• Improve patch quality - Post redacted after-fix Gateway runtime output showing current and legacy protocol behavior, including prompt cancellation.

Findings

• [P1] Accept legacy unknown-method response variants — src/OpenClaw.Shared/WindowsNodeClient.cs:984-995
• [P1] Preserve trusted request-envelope session attribution — src/OpenClaw.Shared/WindowsNodeClient.cs:1356-1364
• [P1] Dispatch cancellation before attribution negotiation — src/OpenClaw.Shared/WindowsNodeClient.cs:481-495

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Protocol change surface	7 files affected, 659 added and 35 removed	A substantial transport change touches invocation dispatch and command-approval session correlation, so compatibility proof needs to cover both old and current Gateway behavior.

Merge-risk options

Maintainer options:

1. Repair the protocol compatibility path (recommended)
   Accept flat and case-insensitive unknown-method responses, preserve the Gateway request-envelope session key, and let cancellation bypass negotiation before requesting fresh runtime proof.
2. Pause the draft
   Keep the branch in draft state if the upstream Gateway contract cannot confirm the required legacy response variants and cancellation ordering.

Technical review

Best possible solution:

Keep the authoritative-envelope trust boundary, but accept documented legacy unknown-method variants, retain trusted request-envelope session keys, and dispatch cancellation independently of feature negotiation with focused regression coverage and redacted real Gateway proof.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level. Targeted tests can feed a flat or mixed-case unknown-method response, a direct request containing params.sessionKey, and an invoke-plus-cancel sequence before negotiation resolves; the current PR code deterministically exhibits all three defects.

Is this the best way to solve the issue?

No. The feature-negotiation design can preserve the intended trust boundary, but its legacy classifier, direct-request attribution, and cancellation ordering must be corrected before it is a maintainable solution.

Full review comments:

• [P1] Accept legacy unknown-method response variants — src/OpenClaw.Shared/WindowsNodeClient.cs:984-995
  Older Gateways can return a flat error string or change the casing of unknown method. This classifier only accepts an object with INVALID_REQUEST and an exact-case message, so the intended legacy mode is unreachable and compatible invocation traffic fails closed.
  Confidence: 0.99
• [P1] Preserve trusted request-envelope session attribution — src/OpenClaw.Shared/WindowsNodeClient.cs:1356-1364
  The request transport’s params.sessionKey is Gateway-stamped, but this branch drops it entirely while creating NodeInvokeRequest. Only nested caller-controlled arguments should be ignored; otherwise approval and execution lose trusted session correlation.
  Confidence: 0.98
• [P1] Dispatch cancellation before attribution negotiation — src/OpenClaw.Shared/WindowsNodeClient.cs:481-495
  Every queued event awaits the feature-negotiation task before switching on its kind. A cancellation received during negotiation waits up to the timeout instead of cancelling the already-started invocation, which can make cancellation ineffective.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8ac00c5f4977.

Labels

Label changes:

• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists focused tests and GitHub Actions, but it has no current-head after-fix Gateway, MCP, terminal, or redacted runtime proof. Add proof after the P1 corrections and redact tokens, endpoints, and device identifiers; updating the PR body should trigger a fresh review, or a maintainer can request @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• remove status: ⏳ waiting on author: Current PR status label is status: 📣 needs proof.

Label justifications:

• P1: The proposed protocol path can prevent existing Gateway-to-node command and cancellation workflows from working correctly.
• merge-risk: 🚨 compatibility: The legacy fallback does not recognize common older-Gateway unknown-method response shapes.
• merge-risk: 🚨 security-boundary: The patch changes which session attribution reaches command approval and execution capabilities.
• merge-risk: 🚨 availability: Cancellation is serialized behind an asynchronous capability negotiation and can arrive too late.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists focused tests and GitHub Actions, but it has no current-head after-fix Gateway, MCP, terminal, or redacted runtime proof. Add proof after the P1 corrections and redact tokens, endpoints, and device identifiers; updating the PR body should trigger a fresh review, or a maintainer can request @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Legacy fallback remains too narrow: The PR only recognizes an object-shaped error with code INVALID_REQUEST and an exact-case message substring. A flat string error such as "unknown method: ..." leaves older Gateways in authoritative mode instead of reaching the advertised legacy fallback. (src/OpenClaw.Shared/WindowsNodeClient.cs:980, 4a137f6b1013)
• Trusted request-envelope attribution is discarded: The direct request transport constructs NodeInvokeRequest without copying params.sessionKey, despite the established Gateway contract and the collaborator review identifying that envelope field as Gateway-stamped. (src/OpenClaw.Shared/WindowsNodeClient.cs:1356, 4a137f6b1013)
• Cancellation waits for negotiation: Queued event traffic always awaits the feature-negotiation task before dispatching either invocation or cancellation. A cancel received during the five-second negotiation window cannot cancel an invocation promptly. (src/OpenClaw.Shared/WindowsNodeClient.cs:483, 4a137f6b1013)
• Maintainer protocol review: A collaborator’s review explicitly requests support for flat and case-variant unknown-method errors, preservation of request-envelope session attribution, and cancellation dispatch without negotiation delay.
• Current main does not contain this branch: The PR head is not an ancestor of current main, and current-main code still uses the pre-PR session-key extraction path. This work is neither implemented on main nor present in release v0.6.12. (src/OpenClaw.Shared/WindowsNodeClient.cs, 8ac00c5f4977)
• Feature-history routing: Recent current-main maintenance of WindowsNodeClient includes Gateway authentication and reconnect work, while an earlier dispatch-invariant hardening commit also touched this central transport file. (src/OpenClaw.Shared/WindowsNodeClient.cs, bc210e048aa9)

Likely related people:

• Barbara Kudiess: Recent current-main work maintained WindowsNodeClient’s Gateway authentication, reconnect, and device-identity behavior. (role: recent area contributor; confidence: high; commits: bc210e048aa9, b46e91e21b45, c04c5fb06238; files: src/OpenClaw.Shared/WindowsNodeClient.cs)
• Scott Hanselman: Current history includes dispatch-under-lock invariant hardening in the same transport file, and the collaborator review gives concrete protocol compatibility guidance for this PR. (role: adjacent transport contributor and reviewer; confidence: medium; commits: 15ed439dc5a3; files: src/OpenClaw.Shared/WindowsNodeClient.cs)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (16 earlier review cycles; latest 8 shown)

• reviewed 2026-08-01T17:58:09.102Z sha 4a137f6 :: needs changes before merge. :: [P1] Accept flat unknown-method fallbacks | [P1] Retain trusted request-envelope session keys | [P1] Do not queue cancellation behind negotiation
• reviewed 2026-08-01T21:45:49.720Z sha 4a137f6 :: found issues before merge. :: [P1] Accept flat unknown-method fallback responses | [P1] Retain trusted request-envelope session attribution | [P1] Dispatch cancellation before feature negotiation
• reviewed 2026-08-02T06:15:07.382Z sha 4a137f6 :: needs changes before merge. :: [P1] Accept legacy unknown-method response shapes | [P1] Preserve trusted request-envelope session attribution | [P1] Dispatch cancellation without waiting for negotiation
• reviewed 2026-08-02T08:00:37.743Z sha 4a137f6 :: needs changes before merge. :: [P1] Recognize legacy unknown-method response variants | [P1] Dispatch cancellation before attribution negotiation
• reviewed 2026-08-02T10:57:18.036Z sha 4a137f6 :: needs changes before merge. :: [P1] Accept legacy unknown-method response variants | [P1] Preserve trusted request-envelope session keys | [P1] Dispatch cancellation before attribution negotiation
• reviewed 2026-08-02T13:17:39.372Z sha 4a137f6 :: found issues before merge. :: [P1] Accept legacy unknown-method response variants | [P1] Preserve trusted request-envelope session keys | [P1] Dispatch cancellation before attribution negotiation
• reviewed 2026-08-02T14:31:26.452Z sha 4a137f6 :: found issues before merge. :: [P1] Accept legacy unknown-method response variants | [P1] Dispatch cancellation before attribution negotiation
• reviewed 2026-08-02T16:41:29.757Z sha 4a137f6 :: needs changes before merge. :: [P1] Accept legacy unknown-method response variants | [P1] Preserve trusted request-envelope session attribution | [P1] Dispatch cancellation before attribution negotiation

[shanselman]

Adversarial maintainer review found blocking protocol regressions, so this draft should not be marked ready yet:

• Legacy negotiation only recognizes an object-shaped, exact-case INVALID_REQUEST error, while this gateway commonly returns a flat string such as unknown method: ...; the compatibility fallback is effectively unreachable.
• The documented request transport's envelope-level params.sessionKey is gateway-stamped and should remain trusted. Only caller-controlled args.sessionKey should be ignored.
• Request cancellation is delayed behind feature negotiation even though request invokes execute immediately, making cancellation late or ineffective; generation changes can also drop a cancel response entirely.

Please accept both string/object unknown-method errors case-insensitively, preserve trusted request-envelope attribution, and dispatch/respond to cancellation without waiting on negotiation. Current merge confidence is 35%.