refactor: add a replaceable node runtime and sidecar adapter proof

[giodl73-repo]

Summary

Adds one replaceable Windows node-runtime boundary, one shared Windows capability
dispatcher, and a non-selectable C# conformance consumer of OpenClaw's proposed
authenticated Rust sidecar contract. It is independent contract proof, not a
second production runtime.

This consolidated Windows adopter PR now:

• introduces INodeRuntimeClient and an injectable factory while keeping
  WindowsNodeClient selected by default;
• moves NodeService and A2UI consumers behind that runtime contract;
• extracts command indexing, bounded execution, duplicate tracking,
  cancellation, telemetry, and completion into the transport-independent
  NodeCapabilityDispatcher;
• requires substitute runtimes to honor connection cancellation and retire
  cancelled candidates without blocking later reconnects;
• independently implements the authenticated framing, handshake, immutable
  configuration, admission, invocation, cancellation, result, and status
  contracts proposed by OpenClaw PR3; and
• routes admitted ordinary native invocations through the same
  NodeCapabilityDispatcher, without adding a second Windows policy or
  execution path.

The former stacked fork proof
#2 has been
fast-forwarded into this branch. The C# runtime remains the production default.

Position in the series

1. OpenClaw #116050 — shared
   Gateway client, bounded node-host foundation, headless binary, and Linux
   Tauri convergence.
2. OpenClaw #116450 — signing,
   lifecycle/reconnect, duplex invocation, admission, Gateway authority,
   connection manifests, and shared conformance.
3. OpenClaw #116863 —
   authenticated/versioned sidecar framing, handshake, immutable configuration,
   and the bounded ordinary-command runtime bridge.
4. This PR — the Windows runtime seam, shared capability dispatcher, and
   independent C# adopter proof.

OpenClaw and openclaw-windows-node are separate repositories, so this PR
cannot be Git-rebased onto #116863. The dependency is contractual: this branch
pins and reproduces #116863's three fixture corpora at OpenClaw head
71c1c8cb23c5647dc07fd4ee1f8663068c92a482. Production Rust selection remains
blocked until that contract is accepted and the remaining adoption gates close.

Ownership boundary

RFC #54 proposes that OpenClaw own the reusable protocol, Gateway authority
semantics, Rust runtime, and conformance corpora. Under that boundary, Windows
retains WinUI, operator behavior, MCP, approvals, native capability handlers,
process/artifact verification, protected bootstrap, concrete IPC, audit,
packaging, rollout, and rollback.

WindowsNodeClient still owns production Gateway wire parsing and response
framing. NodeCapabilityDispatcher owns Windows capability execution. The
sidecar adapter can only deliver authenticated, admitted ordinary invocations
into that dispatcher; it is not an INodeRuntimeClient, launches no process,
chooses no transport, and cannot be selected.

The generic Rust runtime still rejects the reserved system.* namespace. The
existing Windows system.run family therefore stays on C# until OpenClaw owns
an explicit authorization mechanism.

Remaining adoption gates

Before Rust can become selectable, Windows still needs verified artifact/process
launch, protected credential handoff, concrete local IPC, live Gateway pairing
and issued-token lifecycle, duplex sidecar input/progress/heartbeat transport,
process/crash supervision, health and resource proof, product audit export,
packaging, rollout, and rollback.

Validation

• Current rebased head: focused RustSidecar/NodeCapabilityDispatcher tests — 63/63 passed
• Current rebased head: full Shared suite — 3,701 passed, 32 environment-dependent skips
• Current rebased head: focused NodeConnector Connection tests — 22/22 passed
• Prior head: all Debug win-x64 projects built; 60 focused sidecar, 3,462
  Shared, 2,023 Tray, and 519 Connection tests passed
• ./scripts/validate-mxc-e2e.ps1 on the runtime-seam head — 2/2 live Gateway MXC tests passed
• git diff --check — passed
• built-in Codex review plus independent correctness, architecture/API, and
  security reviews — all findings resolved; exact combined-head passes clean

The combined Windows head is
711fe095028a025fa0649c9b8e20f480644a6967. The rebase preserves the current
fail-closed pre-credential handshake authorization gate through the generic
runtime seam. The adapter review also fixed
cancellation/registration races, response ordering, admission lifetime,
handshake role/version binding, result/envelope bounds, serde-compatible typed
and untyped number handling, and bounded canonicalization across JsonElement,
JsonNode, and JsonDocument.

Real behavior proof

Behavior or issue addressed:
Windows needs one migration-safe execution boundary that preserves current
Gateway-to-native behavior while proving that the OpenClaw sidecar contract can
be consumed independently without bypassing Windows policy or handlers.

Real environment tested:
Windows 11, .NET SDK 10.0.302, combined head
711fe095028a025fa0649c9b8e20f480644a6967, OpenClaw sidecar fixtures from
71c1c8cb23c5647dc07fd4ee1f8663068c92a482, and the existing live Gateway/MXC
proof collected on runtime-seam head
c0cfa8ba66802e601de23875b07caf941209e554. The sidecar proof is an in-process
source harness; it does not launch an external Rust binary.

Exact steps or command run after this patch:

1. Build every Windows project at the combined head.
2. Reproduce all three Rust sidecar corpora byte-for-byte in C#.
3. Complete authentication, immutable configuration, admission, invocation,
   cancellation, result, and status flows.
4. Route admitted ordinary commands only through NodeCapabilityDispatcher.
5. Exercise authentication, ordering, identity, admission, serialization,
   cancellation, and resource-bound failures.
6. Run the focused and complete Shared/Tray suites.
7. On the unchanged production C# selection, run the live Gateway MXC harness
   for successful contained system.run and denied tray-data writes.

Evidence after fix:
The rebased head passes 63 focused sidecar/dispatcher tests, 3,701 Shared tests,
and 22 focused Connection tests. Prior-head larger-suite evidence and the
retained live MXC transcript remain recorded; MXC reports 2/2 passed: contained
system.run returned OPENCLAW_GATEWAY_SYSTEM_RUN_MXC_OK, and a write outside
the sandbox failed with Access is denied and fileExists=False.

Observed result after fix:
The incumbent C# runtime still executes real Gateway commands through the shared
dispatcher. Independently, the non-selectable adapter accepts the exact
OpenClaw sidecar contracts, routes ordinary admitted commands into that same
dispatcher, and fails closed on authentication, ordering, identity, admission,
cancellation, serialization, and output/work-bound violations.

What was not tested:
No Rust process was launched; no concrete IPC or protected bootstrap was used;
no live Gateway session selected the Rust runtime; and no system.* sidecar
command, crash recovery, production audit, resource measurement, packaged
artifact, rollout, or rollback was exercised. Production selection remains the
existing C# WindowsNodeClient.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 24, 2026, 1:10 AM ET / 05:10 UTC.

ClawSweeper review

What this changes

The PR adds a replaceable node-runtime interface, moves Windows capability execution into a shared dispatcher, and adds a non-selectable C# conformance adapter for a proposed authenticated sidecar protocol.

Merge readiness

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

Keep open. The branch is conflicted with current main and its new runtime contract omits main’s protocol-compatibility notification path; it also combines three independently risky ownership transfers whose sidecar authority boundary has only in-process proof.

Priority: P2
Reviewed head: 711fe095028a025fa0649c9b8e20f480644a6967
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch has extensive fixture coverage, but current-main compatibility is incomplete and the material authority boundary lacks real behavior proof.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: Authority-chain proof required: the PR body documents fixture and in-process coverage, while its live MXC run is from an earlier head and it explicitly does not launch a sidecar, use protected credential handoff, or exercise a current-head gateway path. Add redacted current-head real gateway/MCP output plus allowed and nearest-forbidden sidecar final-effect evidence before merge. 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	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: Authority-chain proof required: the PR body documents fixture and in-process coverage, while its live MXC run is from an earlier head and it explicitly does not launch a sidecar, use protected credential handoff, or exercise a current-head gateway path. Add redacted current-head real gateway/MCP output plus allowed and nearest-forbidden sidecar final-effect evidence before merge. 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	Current-main compatibility contract: Current main forwards GatewayProtocolCompatibility from the node client through NodeConnector, while GatewayConnectionManager subscribes and gives it to its node coordinator. PR runtime contract omission: The new INodeRuntimeClient event surface has no protocol-compatibility event, so a replacement runtime cannot preserve the current-main forwarding path. Current-main divergence: The PR head is GitHub-dirty against main, and the local comparison shows extensive current-main divergence. A rebase must preserve the newer protocol-compatibility behavior explicitly.
Findings	2 actionable findings	[P1] Preserve protocol compatibility through the runtime seam [P2] Split the three ownership transfers before merge
Security	Needs attention	Prove sidecar authorization before native execution: The adapter’s invocation path can dispatch an admitted sidecar message to a Windows capability handler, while the PR explicitly has no real sidecar process or protected credential handoff. Prove that the nearest unauthorized sidecar is rejected before that final handler execution.

Live Verification

Command: .\build.ps1 -NoTrustRepository

Result: FAIL (failed) — execution before step 1 run: sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.23.0.tgz

sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.23.0.tgz

Assertions:

• FAIL expect_output: 🦞 All builds succeeded!

How this fits together

Gateway connections create a Windows node runtime, then NodeService registers native capabilities before the runtime handshake. Gateway or sidecar invocations flow through the shared dispatcher to Windows handlers, which return results and connection status to the gateway and local MCP consumers.

flowchart LR
  G[Gateway connection request] --> C[Node connection coordinator]
  C --> F[Runtime factory]
  F --> R[Default Windows runtime]
  R --> D[Shared capability dispatcher]
  S[Authenticated sidecar frames] --> A[Sidecar adapter]
  A --> D
  D --> H[Windows capability handlers]
  H --> O[Gateway and MCP results]

Loading

Decision needed

Question	Recommendation
Should this repository land a non-selectable conformance adapter for an unmerged cross-repository sidecar protocol now, or stage only the rebased runtime/dispatcher seam until that protocol is accepted?	Stage the seam: Split out a rebased runtime and dispatcher PR that preserves current-main compatibility behavior, and keep the adapter proof out of the landing path until the upstream protocol is accepted.

Why: The adapter intentionally has no selectable runtime, process launch, protected bootstrap, or concrete IPC, so deciding whether its source-only conformance implementation belongs in this repository is a product and ownership choice.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: Authority-chain proof required: the PR body documents fixture and in-process coverage, while its live MXC run is from an earlier head and it explicitly does not launch a sidecar, use protected credential handoff, or exercise a current-head gateway path. Add redacted current-head real gateway/MCP output plus allowed and nearest-forbidden sidecar final-effect evidence before merge. 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.
• Preserve protocol compatibility through the runtime seam (P1) - Current main now forwards GatewayProtocolCompatibility from WindowsNodeClient through NodeConnector to the connection coordinator, but this new interface has no corresponding event. Since the branch is conflicted with main, rebase it with that event, forwarding, and regression coverage so an incompatible gateway remains visible instead of silently bypassing the coordinator.
• Split the three ownership transfers before merge (P2) - This PR establishes the runtime boundary, the dispatcher, and the sidecar authority adapter together. The repository requires one tested seam per refactor PR; separating these transfers is necessary to review their distinct lifecycle, compatibility, and security invariants.
• Resolve security concern: Prove sidecar authorization before native execution - The adapter’s invocation path can dispatch an admitted sidecar message to a Windows capability handler, while the PR explicitly has no real sidecar process or protected credential handoff. Prove that the nearest unauthorized sidecar is rejected before that final handler execution.
• Resolve merge risk (P1) - The dirty branch must be rebased without losing current-main protocol compatibility reporting to the connection coordinator.
• Resolve merge risk (P1) - The PR combines runtime lifecycle, command dispatch, and a cross-repository sidecar contract, making ownership and upgrade behavior difficult to validate as one change.
• Resolve merge risk (P1) - Authenticated sidecar messages can reach native capability execution, but no current-head proof covers protected key handoff and rejection of a real unauthorized sidecar before handler execution.
• Complete next step (P2) - A maintainer must choose whether the unmerged sidecar contract belongs here before a rebase and split can establish a safe repair boundary.

Findings

• [P1] Preserve protocol compatibility through the runtime seam — src/OpenClaw.Shared/INodeRuntimeClient.cs:36-45
• [P2] Split the three ownership transfers before merge — docs/ARCHITECTURE.md:146-148
• [medium] Prove sidecar authorization before native execution — src/OpenClaw.Shared/RustSidecar/WindowsSidecarCapabilityAdapter.cs:202

Agent review details

Security

Needs attention: The sidecar adapter crosses into native capability execution, but the proposed authenticated boundary has no real process or protected-handoff proof at the current head.

Review metrics

Metric	Value	Why it matters
Patch scope	25 files, +5,688/-626 lines	The size includes runtime lifecycle, capability dispatch, and sidecar protocol work in one draft PR.
Production versus tests	production +2,511, tests +2,458, docs +93	Substantial implementation growth is paired with tests, but the tests remain fixture and in-process coverage.
Ownership transfers	3 authoritative owners added	The architecture ledger records separate runtime, dispatcher, and sidecar-adaptation owners that should be reviewed independently.

Merge-risk options

Maintainer options:

1. Rebase and stage the runtime seam (recommended)
   Preserve protocol-compatibility forwarding on current main and split the runtime/dispatcher work from the sidecar conformance adapter before another merge review.
2. Accept the larger sidecar direction
   Sponsor the adapter as a cross-repository product direction and require real authenticated-sidecar, forbidden-principal, and gateway-path proof before merge.
3. Pause the sidecar adapter
   Keep the experiment out of this repository until the upstream protocol and a selectable production boundary are ready.

Technical review

Best possible solution:

Split and rebase the work: preserve current protocol compatibility in a small runtime/dispatcher change, and keep the sidecar adapter as conformance work until the upstream contract is accepted and can receive real process, gateway, and authority-boundary proof.

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

Yes, source inspection gives a high-confidence merge reproduction: current main forwards protocol compatibility through the node connector, while the new runtime interface omits that event and the PR is conflicted with main.

Is this the best way to solve the issue?

No. A rebased seam must preserve the current-main compatibility contract, and the three ownership transfers should not be landed as one source-only sidecar experiment.

Full review comments:

• [P1] Preserve protocol compatibility through the runtime seam — src/OpenClaw.Shared/INodeRuntimeClient.cs:36-45
  Current main now forwards GatewayProtocolCompatibility from WindowsNodeClient through NodeConnector to the connection coordinator, but this new interface has no corresponding event. Since the branch is conflicted with main, rebase it with that event, forwarding, and regression coverage so an incompatible gateway remains visible instead of silently bypassing the coordinator.
  Confidence: 0.98
• [P2] Split the three ownership transfers before merge — docs/ARCHITECTURE.md:146-148
  This PR establishes the runtime boundary, the dispatcher, and the sidecar authority adapter together. The repository requires one tested seam per refactor PR; separating these transfers is necessary to review their distinct lifecycle, compatibility, and security invariants.
  Confidence: 0.99

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 ccd64bbb7d68.

Labels

Label changes:

• add merge-risk: 🚨 security-boundary: The adapter admits authenticated sidecar traffic into native capability execution without current-head real boundary proof.

Label justifications:

• P2: This is a substantial but not yet released node-runtime refactor with concrete merge blockers.
• merge-risk: 🚨 compatibility: The new runtime contract omits current-main protocol-compatibility forwarding required by the connection coordinator.
• merge-risk: 🚨 availability: The conflicted connection-lifecycle refactor can disrupt node connection and capability availability if rebased incompletely.
• merge-risk: 🚨 security-boundary: The adapter admits authenticated sidecar traffic into native capability execution without current-head real boundary proof.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Authority-chain proof required: the PR body documents fixture and in-process coverage, while its live MXC run is from an earlier head and it explicitly does not launch a sidecar, use protected credential handoff, or exercise a current-head gateway path. Add redacted current-head real gateway/MCP output plus allowed and nearest-forbidden sidecar final-effect evidence before merge. 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

Security concerns:

• [medium] Prove sidecar authorization before native execution — src/OpenClaw.Shared/RustSidecar/WindowsSidecarCapabilityAdapter.cs:202
  The adapter’s invocation path can dispatch an admitted sidecar message to a Windows capability handler, while the PR explicitly has no real sidecar process or protected credential handoff. Prove that the nearest unauthorized sidecar is rejected before that final handler execution.
  Confidence: 0.93

What I checked:

• Current-main compatibility contract: Current main forwards GatewayProtocolCompatibility from the node client through NodeConnector, while GatewayConnectionManager subscribes and gives it to its node coordinator. (src/OpenClaw.Connection/NodeConnector.cs:28, ccd64bbb7d68)
• PR runtime contract omission: The new INodeRuntimeClient event surface has no protocol-compatibility event, so a replacement runtime cannot preserve the current-main forwarding path. (src/OpenClaw.Shared/INodeRuntimeClient.cs:36, 711fe095028a)
• Current-main divergence: The PR head is GitHub-dirty against main, and the local comparison shows extensive current-main divergence. A rebase must preserve the newer protocol-compatibility behavior explicitly. (src/OpenClaw.Connection/NodeConnector.cs:1, ccd64bbb7d68)
• Repository scope policy: The repository policy requires one tested seam per refactor PR; this branch records three new authoritative owners: runtime boundary, dispatcher, and sidecar adaptation. (docs/ARCHITECTURE.md:146, 711fe095028a)
• Sidecar proof boundary: The sidecar migration document states that the adapter is not selectable and lacks process launch, protected bootstrap, concrete IPC, and pairing parity; fixture and in-process tests therefore do not prove the authority boundary in a real runtime. (docs/RUST_NODE_RUNTIME_MIGRATION.md:39, 711fe095028a)
• Feature-history provenance: Current main’s protocol-compatibility path appears to date to the connection compatibility change authored by Barbara Kudiess on 2026-08-19. (src/OpenClaw.Connection/NodeConnector.cs:28, 428db773d8be)

Likely related people:

• Barbara Kudiess: Authored the current-main change that added the node protocol-compatibility forwarding path the runtime seam must preserve. (role: introduced current protocol-compatibility behavior; confidence: high; commits: 428db773d8be; files: src/OpenClaw.Connection/NodeConnector.cs, src/OpenClaw.Connection/INodeConnector.cs, src/OpenClaw.Shared/WindowsNodeClient.cs)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Rebase onto current main and preserve GatewayProtocolCompatibility through the runtime interface, connector, and coordinator tests.
• Split the runtime boundary, dispatcher extraction, and sidecar adapter into separately reviewable ownership transfers.
• Add redacted current-head MCP or gateway proof for the dispatcher and final-effect evidence that an unauthorized sidecar is rejected before any native handler runs.

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 (38 earlier review cycles; latest 8 shown)

• reviewed 2026-08-02T14:31:00.983Z sha 3ca913a :: needs real behavior proof before merge. :: none
• reviewed 2026-08-02T16:41:48.116Z sha 3ca913a :: needs real behavior proof before merge. :: [P1] Preserve the public node-client type contract
• reviewed 2026-08-02T17:57:57.698Z sha 3ca913a :: needs real behavior proof before merge. :: none
• reviewed 2026-08-02T21:29:51.898Z sha 3ca913a :: needs real behavior proof before merge. :: none
• reviewed 2026-08-02T23:03:30.346Z sha 3ca913a :: needs real behavior proof before merge. :: none
• reviewed 2026-08-03T08:00:31.629Z sha 3ca913a :: needs real behavior proof before merge. :: none
• reviewed 2026-08-12T19:29:54.378Z sha 711fe09 :: needs real behavior proof before merge. :: [P2] Split the three ownership transfers before merge
• reviewed 2026-08-12T19:39:49.855Z sha 711fe09 :: needs real behavior proof before merge. :: [P2] Split the runtime, dispatcher, and sidecar transfers

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30575111112
• Updated: 2026-07-30T19:31:05.148Z

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31633051072
• Updated: 2026-08-12T19:31:34.570Z

[shanselman]

Closing the stale speculative sidecar bundle. It lacks current compatibility propagation and protected IPC proof; preserve the design in a smaller proposal if sponsored.