feat(windows): add managed tool setup controls to Gateway Tools

[MythiliMur]

Summary

Add the package-owned Gateway Tools Control UI as the follow-up surface for the Gateway Tool Runtime Bridge in #92.

This PR provides the browser-facing management controls for a user-installed, broker-registered tool:

• select/register an installed executable;
• request a bounded scan of approved locations;
• view bounded registration, setup, and Gateway verification state;
• start the registered tool's managed interactive setup in the human desktop session;
• request Gateway-agent verification;
• enable, disable, or remove a registration.

Dependency

This PR depends on #92 and must not merge first.

PR #92 owns the authoritative Gateway Tool Runtime Bridge: broker authorization, executable validation, managed-profile lifecycle, ACL policy, protected-secret handling, controlled setup launch, Gateway-agent verification, and the Control UI Adapter contract.

This PR consumes only that constrained contract. It does not duplicate the registry, profile policy, shim generation, broker, or privileged process-launch logic.

Control UI boundary

The package-owned Gateway Tools Control UI communicates through the package-owned Control UI Adapter, using a fixed authenticated allowlist:

listTools
registerTool
scanTools
startInteractiveSetup
verifyTool
setToolEnabled
unregisterTool

Browser-safe responses expose only:

• opaque registration identity;
• display alias;
• enabled/disabled state;
• setup state;
• Gateway verification state; and
• bounded user-safe messages.

The isolated Gateway plugin remains unprivileged. It must not directly connect to the desktop-user broker pipe and receives no authorization exemption.

Managed setup behavior

When the user selects Start setup, the UI requests an operation for one existing registration. The Runtime Bridge then:

1. provisions or opens that registration's managed profile;
2. starts only the validated registered executable;
3. starts it in the human interactive desktop session;
4. applies only the tool's reviewed managed-profile configuration; and
5. returns only bounded setup/process state.

The tool performs its normal documented setup itself. The Control UI, adapter, broker, and bridge must not receive, render, parse, or persist external-service pages, codes, callbacks, tokens, account identity, or raw tool output.

Security requirements

• No executable/profile paths, usernames, SIDs, raw diagnostics, profile contents, account identity, tokens, secrets, or external-service setup data in UI/API responses.
• No browser-side direct process launch or arbitrary command execution.
• No UI/plugin authority to edit a tool's declared runtime configuration, ACLs, shims, secret state, or future registration policy.
• No replacement of the broker as the privileged package-owned boundary.

Validation

This follow-up will add UI/route tests demonstrating the fixed operation allowlist and browser-safe DTO redaction. The implementation is intentionally dependent on the #92 broker contract.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 22, 2026, 1:08 AM ET / 05:08 UTC.

ClawSweeper review

What this changes

The branch adds a persisted tool registry, a desktop-user named-pipe broker, and command shims exposed to the isolated Gateway, plus tests and design documentation.

Merge readiness

⛔ Blocked before merge - 16 items remain

Keep open as unfinished dependent work. The collaborator-authored PR shares its entire pinned head with the runtime-bridge PR, has no distinct Control UI implementation yet, and contains blocking runtime defects.

Priority: P2
Reviewed head: 1630fb534ee93aab612d7a1fc90a97459f10e00c

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	Useful groundwork exists, but native execution defects, incomplete profile enforcement, and missing authority-boundary proof prevent a quality-ready verdict.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: Authority-chain proof required: supplied tests call the broker service directly using synthetic executable files; they do not exercise the native pipe-to-registry-to-agent execution path. Show the allowed adapter's final effect, rejection of the isolated agent and unauthorized callers before writes, and disabled/reassigned-target handling before subsequent execution. Redacted Windows terminal traces are suitable. Separately, the new persisted store and profile lifecycle lack fresh/existing-install compatibility proof; the collaborator exemption does not waive these scoped requirements. 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)	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: supplied tests call the broker service directly using synthetic executable files; they do not exercise the native pipe-to-registry-to-agent execution path. Show the allowed adapter's final effect, rejection of the isolated agent and unauthorized callers before writes, and disabled/reassigned-target handling before subsequent execution. Redacted Windows terminal traces are suitable. Separately, the new persisted store and profile lifecycle lack fresh/existing-install compatibility proof; the collaborator exemption does not waive these scoped requirements. 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	8 items	Pinned scope and dependency: The introduced delta is 207d19d..1630fb5. GitHub confirms #92 remains open and draft at that identical head. The captured body explicitly requires that dependency to merge first. The verified test merge has the exact main and PR-head parents; its changes match the introduced files. Current main and release do not contain this bridge: Inspected Gateway source, the existing Control UI handoff, and Gateway file inventories on main and release ee41ab7. Existing clawctl open delegates to upstream dashboard handoff; it does not manage tool registrations. The latest release is v2026.9.4-msix.3, published September 19. No merged replacement was established. Native serialization mismatch: The launcher enables PublishAot for runtime-specific builds. Both new owners use reflection-based JSON overloads without generated metadata, including an object-valued response. Existing GatewayConfigurationStore and ControlUiHandoff demonstrate the generated-context contract.
Findings	6 actionable findings	[P1] [P1] Use generated JSON metadata throughout both new owners [P1] [P1] Require agent verification before exposing a registration [P1] [P1] Apply the managed profile before advertising it as ready
Security	Needs attention	Shell expansion can change the approved executable: Generated batch shims interpolate accepted executable paths without preserving percent-variable literals, allowing invocation to differ from the registered target. Adapter authorization is not established by a user SID: The authorizer admits the desktop identity without identifying the intended Control UI Adapter. No real-boundary evidence establishes the allowed caller, rejection of unauthorized callers, or invalidation of stale registrations before their next execution.

How this fits together

The Windows package launches OpenClaw inside an isolated agent account. This bridge records desktop-approved executables and adds generated command shims to the Gateway's process environment.

flowchart LR
  A[Desktop caller] --> B[Broker authorization]
  B --> C[Tool registry]
  C --> D[Generated command shims]
  D --> E[Gateway process environment]
  E --> F[Tool execution in isolated account]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: Authority-chain proof required: supplied tests call the broker service directly using synthetic executable files; they do not exercise the native pipe-to-registry-to-agent execution path. Show the allowed adapter's final effect, rejection of the isolated agent and unauthorized callers before writes, and disabled/reassigned-target handling before subsequent execution. Redacted Windows terminal traces are suitable. Separately, the new persisted store and profile lifecycle lack fresh/existing-install compatibility proof; the collaborator exemption does not waive these scoped requirements. 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.
• [P1] Use generated JSON metadata throughout both new owners (P1) - The packaged launcher enables NativeAOT, but this response serialization, request/payload deserialization, and registry persistence use reflection-based overloads. These paths lack the generated metadata required by the shipped executable; even an error response cannot be serialized reliably. Add contract-specific contexts covering every request, store, and response variant, including the concrete values currently hidden behind object, and exercise the native entrypoint.
• [P1] Require agent verification before exposing a registration (P1) - A new registration is immediately enabled, and PrepareRuntime emits its shim whenever desktop-side File.Exists succeeds. Verify repeats that same check without invoking the isolated account. Selecting an executable in a desktop-private directory therefore reports availability and exposes a command the Gateway cannot execute, despite the response telling the user to verify before enabling. Persist successful isolated-session verification and gate enablement/shim generation on it.
• [P1] Apply the managed profile before advertising it as ready (P1) - The profile directory created here never reaches WriteShim, which launches only the executable and forwarded arguments. A registered tool consequently uses its normal agent-account profile instead of the supposedly managed profile; createRuntimeProfile still reports success. Carry the reviewed tool-specific profile setting through the actual child launch, or keep this operation unavailable until that contract exists.
• [P1] Preserve the agent-owned Node runtime's PATH precedence (P1) - The new shim directory precedes the required Node directory, while NormalizeCommand permits node, npm, and npx. Registering node therefore creates a node.cmd that can replace the agent-owned runtime for shell-resolved child commands, violating the existing runtime selection contract and potentially breaking agent commands. Preserve the Node directory's precedence and reject aliases reserved by the runtime.
• [P1] Preserve literal executable paths when generating shims (P1) - Quoting does not stop %NAME% expansion in a batch file. An existing executable under a valid Windows directory such as C:\Tools\%USERNAME%\tool.exe passes registration, but the generated shim expands that segment under the agent account and invokes a different path or fails. This defeats the approved-target guarantee. Use a launch mechanism that preserves the literal target, or reject and safely handle shell-expanding path characters.
• [P2] Bound connected-client reads and writes (P2) - The timeout token only reaches WaitForConnectionAsync; serving the client receives the outer token, which production supplies as CancellationToken.None. An authorized client that connects but never sends a newline can hold the single pipe instance forever, blocking every later management request and preventing idle shutdown. Apply a per-request deadline through reads and response writes and recover the accept loop after a stalled client.
• Resolve security concern: Shell expansion can change the approved executable - Generated batch shims interpolate accepted executable paths without preserving percent-variable literals, allowing invocation to differ from the registered target.
• Resolve security concern: Adapter authorization is not established by a user SID - The authorizer admits the desktop identity without identifying the intended Control UI Adapter. No real-boundary evidence establishes the allowed caller, rejection of unauthorized callers, or invalidation of stale registrations before their next execution.
• Resolve merge risk (P1) - The intended adapter-only authorization boundary is not established: the implementation checks only the desktop user's SID. Prove the allowed caller and rejection of the isolated agent and other unauthorized callers before registry writes.
• Resolve merge risk (P1) - Persisted registrations and generated shims lack final-effect evidence for disabled or reassigned targets; prove that stale authority cannot select an unintended executable at the next permitted launch.
• Resolve merge risk (P1) - The new registration store and profile lifecycle need fresh-install and existing-install compatibility evidence, including preservation of existing Gateway configuration and session state.
• Complete next step (P2) - Complete and land feat(windows): add Gateway Tool Runtime Bridge shared profiles #92 first, then present the distinct Control UI/adapter changes with a current description and applicable Windows validation.
• Improve patch quality - Resolve the shared findings in the runtime-bridge dependency and add the distinct Control UI implementation.
• Improve patch quality - Provide redacted native Windows evidence for allowed and forbidden callers and stale registration handling at the final side effect.
• Improve patch quality - Validate fresh and existing installations, including registry persistence, Gateway lifecycle, and Node command resolution.

Findings

• [P1] [P1] Use generated JSON metadata throughout both new owners — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:90
• [P1] [P1] Require agent verification before exposing a registration — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:67-70
• [P1] [P1] Apply the managed profile before advertising it as ready — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:133-136
• [high] Shell expansion can change the approved executable — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:212
• [medium] Adapter authorization is not established by a user SID — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:155

Agent review details

Security

Needs attention: Executable approval crosses account boundaries, but literal target preservation and adapter/final-effect authorization need repair or proof.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +773/-12; tests +183/-0; docs +169/-0	The growth implements bridge infrastructure, while the separately claimed browser UI remains absent.
Distinct follow-up commits	0 beyond the dependency's pinned head	Both open PRs currently point to the same commit and need separate review boundaries.

Root-cause cluster

Relationship: partial_overlap
Canonical: #92
Summary: The current implementation is identical to the dependency, while the stated follow-up UI remains distinct unfinished work.

Members:

• canonical: feat(windows): add Gateway Tool Runtime Bridge shared profiles #92 - The body assigns authoritative runtime-bridge ownership to this open draft, which currently has the same head.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Finish and validate the bridge first (recommended)
   Resolve the shared runtime defects in the dependency, establish authorization and upgrade evidence, and then review the distinct UI layer.
2. Keep activation deferred
   Leave this draft unmerged until the runtime bridge and its constrained adapter contract are complete.

Technical review

Best possible solution:

Keep one authoritative bridge in the dependency, then add a thin Control UI adapter that consumes verified, profile-scoped operations with explicit lifecycle and upgrade behavior.

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

Yes, source inspection establishes focused triggers for the patch defects, including native JSON serialization, unverified registration, and a connected client that never finishes a request. No failing Windows execution was performed.

Is this the best way to solve the issue?

No, the current branch exposes incomplete bridge behavior rather than the promised management UI; the maintainable path is to finish the dependency's owner and add only its constrained UI consumer here.

Full review comments:

• [P1] [P1] Use generated JSON metadata throughout both new owners — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:90
  The packaged launcher enables NativeAOT, but this response serialization, request/payload deserialization, and registry persistence use reflection-based overloads. These paths lack the generated metadata required by the shipped executable; even an error response cannot be serialized reliably. Add contract-specific contexts covering every request, store, and response variant, including the concrete values currently hidden behind object, and exercise the native entrypoint.
  Confidence: 0.99
• [P1] [P1] Require agent verification before exposing a registration — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:67-70
  A new registration is immediately enabled, and PrepareRuntime emits its shim whenever desktop-side File.Exists succeeds. Verify repeats that same check without invoking the isolated account. Selecting an executable in a desktop-private directory therefore reports availability and exposes a command the Gateway cannot execute, despite the response telling the user to verify before enabling. Persist successful isolated-session verification and gate enablement/shim generation on it.
  Confidence: 0.99
• [P1] [P1] Apply the managed profile before advertising it as ready — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:133-136
  The profile directory created here never reaches WriteShim, which launches only the executable and forwarded arguments. A registered tool consequently uses its normal agent-account profile instead of the supposedly managed profile; createRuntimeProfile still reports success. Carry the reviewed tool-specific profile setting through the actual child launch, or keep this operation unavailable until that contract exists.
  Confidence: 0.99
• [P1] [P1] Preserve the agent-owned Node runtime's PATH precedence — src/OpenClaw.Launcher/Gateway/SessionGatewayClient.cs:314-317
  The new shim directory precedes the required Node directory, while NormalizeCommand permits node, npm, and npx. Registering node therefore creates a node.cmd that can replace the agent-owned runtime for shell-resolved child commands, violating the existing runtime selection contract and potentially breaking agent commands. Preserve the Node directory's precedence and reject aliases reserved by the runtime.
  Confidence: 0.96
• [P1] [P1] Preserve literal executable paths when generating shims — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:210-213
  Quoting does not stop %NAME% expansion in a batch file. An existing executable under a valid Windows directory such as C:\Tools\%USERNAME%\tool.exe passes registration, but the generated shim expands that segment under the agent account and invokes a different path or fails. This defeats the approved-target guarantee. Use a launch mechanism that preserves the literal target, or reject and safely handle shell-expanding path characters.
  Confidence: 0.97
• [P2] [P2] Bound connected-client reads and writes — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:57
  The timeout token only reaches WaitForConnectionAsync; serving the client receives the outer token, which production supplies as CancellationToken.None. An authorized client that connects but never sends a newline can hold the single pipe instance forever, blocking every later management request and preventing idle shutdown. Apply a per-request deadline through reads and response writes and recover the accept loop after a stalled client.
  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 medium; reviewed against 207d19d0fd28.

Labels

Label changes:

• add P2: This is a bounded new Windows integration capability without evidence of an urgent shipped-user regression.
• add merge-risk: 🚨 compatibility: The branch adds durable registration state and changes Gateway command resolution without existing-install compatibility proof.
• add merge-risk: 🚨 security-boundary: Persisted executable approval crosses into the isolated agent, while adapter authentication and final target enforcement remain unresolved.
• add merge-risk: 🚨 availability: Reflection-based serialization breaks the native broker path, and an incomplete pipe request can monopolize its only connection.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish and patch quality is 🧂 unranked krab.
• add 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: supplied tests call the broker service directly using synthetic executable files; they do not exercise the native pipe-to-registry-to-agent execution path. Show the allowed adapter's final effect, rejection of the isolated agent and unauthorized callers before writes, and disabled/reassigned-target handling before subsequent execution. Redacted Windows terminal traces are suitable. Separately, the new persisted store and profile lifecycle lack fresh/existing-install compatibility proof; the collaborator exemption does not waive these scoped requirements. 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.

Label justifications:

• P2: This is a bounded new Windows integration capability without evidence of an urgent shipped-user regression.
• merge-risk: 🚨 security-boundary: Persisted executable approval crosses into the isolated agent, while adapter authentication and final target enforcement remain unresolved.
• merge-risk: 🚨 compatibility: The branch adds durable registration state and changes Gateway command resolution without existing-install compatibility proof.
• merge-risk: 🚨 availability: Reflection-based serialization breaks the native broker path, and an incomplete pipe request can monopolize its only connection.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish 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: Authority-chain proof required: supplied tests call the broker service directly using synthetic executable files; they do not exercise the native pipe-to-registry-to-agent execution path. Show the allowed adapter's final effect, rejection of the isolated agent and unauthorized callers before writes, and disabled/reassigned-target handling before subsequent execution. Redacted Windows terminal traces are suitable. Separately, the new persisted store and profile lifecycle lack fresh/existing-install compatibility proof; the collaborator exemption does not waive these scoped requirements. 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:

• [high] Shell expansion can change the approved executable — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:212
  Generated batch shims interpolate accepted executable paths without preserving percent-variable literals, allowing invocation to differ from the registered target.
  Confidence: 0.97
• [medium] Adapter authorization is not established by a user SID — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:155
  The authorizer admits the desktop identity without identifying the intended Control UI Adapter. No real-boundary evidence establishes the allowed caller, rejection of unauthorized callers, or invalidation of stale registrations before their next execution.
  Confidence: 0.94

What I checked:

• Pinned scope and dependency: The introduced delta is 207d19d..1630fb5. GitHub confirms feat(windows): add Gateway Tool Runtime Bridge shared profiles #92 remains open and draft at that identical head. The captured body explicitly requires that dependency to merge first. The verified test merge has the exact main and PR-head parents; its changes match the introduced files. (1630fb534ee9)
• Current main and release do not contain this bridge: Inspected Gateway source, the existing Control UI handoff, and Gateway file inventories on main and release ee41ab7. Existing clawctl open delegates to upstream dashboard handoff; it does not manage tool registrations. The latest release is v2026.9.4-msix.3, published September 19. No merged replacement was established. (src/OpenClaw.Launcher/Gateway/ControlUiHandoff.cs:12, 207d19d0fd28)
• Native serialization mismatch: The launcher enables PublishAot for runtime-specific builds. Both new owners use reflection-based JSON overloads without generated metadata, including an object-valued response. Existing GatewayConfigurationStore and ControlUiHandoff demonstrate the generated-context contract. (src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:90, 1630fb534ee9)
• Registration-to-execution chain: Register defaults Enabled to true; readiness is desktop-side File.Exists; PrepareRuntime emits every enabled available registration; SessionGatewayClient puts these shims before the agent Node directory. Verify performs no isolated-session execution. The profile directory is created but never supplied to the executable. (src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:69, 1630fb534ee9)
• Authority and transport coverage: The pipe restricts callers to the current user and checks that user's SID, but does not identify the package-owned adapter. The single-client server applies its deadline only while waiting for a connection. Added tests call DispatchAsync directly with synthetic executable files; they do not exercise the real pipe, isolated-account rejection, command execution, or revoked/reassigned registrations. (src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:152, 1630fb534ee9)
• Persisted-state and implementation gaps: The branch introduces gateway-tools.json schema version 1 and workspace-owned profile directories. The design instead specifies persistent managed profiles and reviewed per-tool configuration. startInteractiveSetup always returns unavailable, scanTools has no dispatcher route, and no browser UI or Control UI Adapter is added. Fresh-install and existing-install compatibility evidence is absent from the captured material. (src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:209, 1630fb534ee9)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• anna-dingler: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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.