feat: run commands through an attached session guest helper

[paulcam206]

What Problem This Solves

Commands need a NativeAOT-safe way to reach a session guest without relying on a shell or flattening caller arguments into a command line.

User Impact

There is no user-visible invocation yet. The later session commands have a transport that preserves arguments exactly across the host/guest boundary.

Why This Change Was Made

The v1 SessionLaunchProtocol defines the request/result contract between host and guest. openclaw-session-host is the NativeAOT guest helper, and SessionProcessLauncher starts it without a shell.

Arguments cross that boundary as JSON rather than a flattened command line, avoiding Windows quoting and tokenization changes. The protocol is established now, but no command invokes it in this layer.

This is intentionally execution plumbing only: session ownership, provisioning, routing, and end-user commands are deferred to the lifecycle layer.

Review fixes addressed

The helper now rejects every non-Attached mode, including undefined numeric enum values, before calling the process launcher. A regression proves no launch occurs. The later gateway layer explicitly evolves this contract to support Detached.

Current validation

Current layer head: b0e304adee62aa6caf49a68e0fa9e49ef979ec7e. This layer is included in the final integrated stack tip cce2b02f3acd5791654b7a6b1a5a9c27db5ff63b rebased onto 685ee93b7ebbec1e784205a3544c460bea740e11.

Integrated local gates: exact .NET SDK 10.0.100; Test-DotNetQuality.ps1 with 0 warnings/errors; full solution tests 642/642; NativeAOT x64 and ARM64 publishes for both launcher and session host; NativeAOT CLI, deployment, MXC, signing, runtime-input, release-identity, bundle, isolation-plugin, and packaging-relevance policy suites.

Live x64 MXC evidence: final-tip Developer Mode deployment registered OpenClaw.Gateway_0.1.2451.40134_x64__kaa03rpbbqef6 from workflow payload run 35191206689; openclaw --version returned OpenClaw 2026.9.4 (3a9d69d); clawctl status confirmed the isolated session was running. Earlier final-tip validation also exercised setup, Node.js 24.20.0 reuse, package-qualified activation, detached gateway launch, and redacted diagnostics collection.

Signed package evidence: local NativeAOT x64 and ARM64 packages and a multi-architecture bundle were composed and test-signed. Elevated upgrade validation passed all four proof-release transitions (v0.0.0.0 and v0.0.0.1, standalone and bundle), retained package-family LocalState in every transition, and accepted fresh standalone and bundle installs. The temporary certificate and test package were removed, then the Developer Mode registration was restored.

Layer 3 of 12. Parent: #44 - feat/session-mxc-backend

[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 maintainer review before merge. Reviewed September 17, 2026, 4:01 PM ET / 20:01 UTC (Revision 18).

ClawSweeper review

What this changes

Adds a packaged Windows guest helper that reads JSON launch requests, runs attached commands without shell interpretation, and records their results.

Merge readiness

✅ Ready for maintainer review

Keep open: this is a distinct, useful layer absent from current main and the latest release. No blocking defect was found in the introduced changes; the collaborator-authored stack remains active.

Priority: P2
Reviewed head: b0e304adee62aa6caf49a68e0fa9e49ef979ec7e

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, coherent stack layer with coordinated packaging checks and no supported blocking finding.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored layer is exempt from ordinary contributor proof. Its helper consumes requests under its existing process identity and adds no cross-principal caller or ownership decision requiring an authority-proof exception; reported integrated execution and install/upgrade checks remain supplemental.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-authored layer is exempt from ordinary contributor proof. Its helper consumes requests under its existing process identity and adds no cross-principal caller or ownership decision requiring an authority-proof exception; reported integrated execution and install/upgrade checks remain supplemental.
Evidence reviewed	9 items	Introduced scope verified: The complete local comparison against the pinned merge base confirms 16 files with 985 additions and no deletions. The supplied test merge is stale and was not used to infer removal of current-main behavior. Execution boundary and mode guard: The helper validates requests and rejects all modes other than Attached before invoking the launcher. The launcher uses UseShellExecute=false and ArgumentList, inherits console handles, waits for completion, and returns the child exit code. No production host caller is introduced in this layer. Transport contract explains the separate helper: The existing MXC execution contract accepts a command-line string and expressly requires arbitrary arguments to travel as request data through a controlled helper. This is an affirmative MXC contract dependency, not a dependency on Codex Code Mode or its harness.
Findings	None	None.
Security	None	None.

How this fits together

The Windows package launches OpenClaw and bundles its runtime dependencies. This layer adds a guest-side execution helper for later isolated-session commands, accepting executable, argument, environment, and working-directory data and returning a separate execution result.

flowchart LR
  A[JSON launch request] --> B[Guest helper]
  B --> C[Validate request and attached mode]
  C --> D[Launch child without shell]
  D --> E[Inherited console streams]
  D --> F[Exit code and result file]
  C --> G[Failure result]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test growth	Production/build +704 lines; tests/test configuration +281 lines; 0 removed	The added code establishes the stated guest protocol, executable, and coordinated packaging validation.

Technical review

Best possible solution:

Keep one versioned guest request protocol and package its helper together with the launcher, leaving session ownership and routing to the dedicated lifecycle layer.

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

Not applicable: this PR introduces internal execution plumbing rather than reporting a current-main failure; runtime behavior was not executed during this read-only review.

Is this the best way to solve the issue?

Yes: a source-generated JSON request and shell-free guest launcher fit the existing MXC string-command boundary without introducing a competing user-facing route.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 685ee93b7ebb.

Labels

Label justifications:

• P2: This is a bounded execution foundation for the active Windows isolation stack, with no current user-facing invocation or urgent regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored layer is exempt from ordinary contributor proof. Its helper consumes requests under its existing process identity and adds no cross-principal caller or ownership decision requiring an authority-proof exception; reported integrated execution and install/upgrade checks remain supplemental.

Evidence

What I checked:

• Introduced scope verified: The complete local comparison against the pinned merge base confirms 16 files with 985 additions and no deletions. The supplied test merge is stale and was not used to infer removal of current-main behavior. (b0e304adee62)
• Execution boundary and mode guard: The helper validates requests and rejects all modes other than Attached before invoking the launcher. The launcher uses UseShellExecute=false and ArgumentList, inherits console handles, waits for completion, and returns the child exit code. No production host caller is introduced in this layer. (src/OpenClaw.SessionHost/Program.cs:46, b0e304adee62)
• Transport contract explains the separate helper: The existing MXC execution contract accepts a command-line string and expressly requires arbitrary arguments to travel as request data through a controlled helper. This is an affirmative MXC contract dependency, not a dependency on Codex Code Mode or its harness. (src/OpenClaw.Launcher/Mxc/MxcSessionContracts.cs:97, b0e304adee62)
• Packaging and signing remain coordinated: MSIX composition publishes the architecture-specific helper before evaluating package content and records its hashes. Signing validation checks inventory paths, lengths, hashes, executable presence, and exact file-set membership; the tests add a tampered-helper rejection case. No action reference, permission, credential source, or third-party package dependency is added. (scripts/Test-SigningInputs.ps1:382, b0e304adee62)
• Current-main behavior remains different: Current main runs packaged OpenClaw directly through GatewayLauncher and its Windows job. Its source tree contains neither SessionHost nor SessionProtocol, so the existing shell-free host launch does not replace this guest request transport. (src/OpenClaw.Launcher/GatewayLauncher.cs:15, 685ee93b7ebb)
• Latest release checked: GitHub identifies v2026.9.4-msix.0 as the latest release, published September 17, and targeting the inspected main commit. That release does not contain the new helper. (685ee93b7ebb)

Likely related people:

• xlinush: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• paulcam206: 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.

History

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

• reviewed 2026-09-16T22:48:44.622Z sha 29254ed :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T01:51:37.156Z sha 9f58a64 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:10:39.880Z sha b0e304a :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:23:14.772Z sha b0e304a :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T17:04:52.691Z sha b0e304a :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:00:34.668Z sha b0e304a :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:23:24.173Z sha b0e304a :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:40:17.461Z sha b0e304a :: needs maintainer review before merge. :: none