feat: manage the OpenClaw gateway inside the isolated session

[paulcam206]

What Problem This Solves

An isolated gateway needs explicit lifecycle control and ownership checks so an operator does not accidentally stop a different process listening on the same port.

User Impact

clawctl gateway-service start, status, and stop manage a gateway in the owned session. The service is detached from the calling console and is stopped with its kill-on-close job.

Why This Change Was Made

Gateway supervision records ownership using PID and process creation time, and verifies listener ownership. When --port is omitted, OpenClaw's own gateway.port configuration wins; --port is used only when the operator pins it.

Review fixes addressed

• The guest's Node runtime directory is delivered as a PathPrefix and prepended to the guest PATH; no host PATH replaces the guest environment.
• A teardown after an unconfirmed launch clears the pending record under the lifecycle lock and proceeds. Ordinary gateway-service stop remains conservative.
• An explicitly configured guest working directory is persisted and honored; the shared workspace remains the default.
• Diagnostic staging reads use handle-bound containment checks, so the validated object is the object read.
• Reconciliation state persists across a failed replacement, and pending-launch recovery exercises the production protocol.

Current validation

Current layer head: 056de40546c2e40ab40864bf6d9b659184a4382f. 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 6 of 12. Parent: #47 - feat/session-agent-shell. Child: #49 - feat/session-logon-recovery

[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 17, 2026, 4:02 PM ET / 20:02 UTC (Revision 28).

ClawSweeper review

What this changes

Adds commands to start, inspect, and stop a detached OpenClaw gateway inside the isolated Windows session, with persisted process identity and supervised cleanup.

Merge readiness

⛔ Blocked before merge - 5 items remain

This remains useful, collaborator-authored work that is absent from the default branch. No blocking code defect was established, but the gateway-specific authority and saved-settings proof gaps remain unresolved.

Priority: P2
Reviewed head: 056de40546c2e40ab40864bf6d9b659184a4382f

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The implementation has useful native-process coverage and no established blocking defect, while authority and configuration-upgrade evidence remain incomplete.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows MXC evidence supports detached launch, but does not show allowed gateway exchanges alongside rejection of guest workspace replacement and stale generations before host file effects. This scoped requirement applies despite the collaborator exemption from unrelated runtime proof; shared-helper and mocked gateway tests are supplemental. 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 stronger real behavior proof before merge: Authority-chain proof required: the captured Windows MXC evidence supports detached launch, but does not show allowed gateway exchanges alongside rejection of guest workspace replacement and stale generations before host file effects. This scoped requirement applies despite the collaborator exemption from unrelated runtime proof; shared-helper and mocked gateway tests are supplemental. 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	10 items	Verified review boundary: The local introduced delta matches the supplied 28-file merge-base-to-head boundary: 5,100 additions and 61 deletions. The supplied test merge is stale and was not used to claim that merging removes default-branch behavior. Still necessary on the default branch: The default-branch command tree exposes setup rather than isolated gateway lifecycle controls. Its README describes isolated-session execution as future work; the supplied related PRs remain open, not merged replacements. Release boundary: The latest supplied release, v2026.9.4-msix.0, points at the inspected default-branch revision without these controls.
Findings	None	None.
Security	Needs attention	Verify guest rejection before host filesystem effects: Gateway requests, result reads, and cleanup use a guest-writable workspace under host authority. Existing handle and generation safeguards are promising, but the supplied execution evidence does not establish their final-effect behavior for guest replacement or stale-session attempts through this gateway path.

How this fits together

The Windows package launcher sends gateway requests through MXC to a helper inside the isolated agent session. The helper supervises the gateway and returns process and listener observations used by the launcher’s lifecycle commands.

flowchart TD
  A[Operator gateway command] --> B[Launcher lifecycle controller]
  C[Saved configuration and process identity] --> B
  B --> D[Validated workspace exchange]
  D --> E[MXC guest helper]
  E --> F[Supervised gateway process]
  F --> G[Process and listener observations]
  G --> B
  B --> H[Operator status or stop result]

Loading

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows MXC evidence supports detached launch, but does not show allowed gateway exchanges alongside rejection of guest workspace replacement and stale generations before host file effects. This scoped requirement applies despite the collaborator exemption from unrelated runtime proof; shared-helper and mocked gateway tests are supplemental. 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.
• Resolve security concern: Verify guest rejection before host filesystem effects - Gateway requests, result reads, and cleanup use a guest-writable workspace under host authority. Existing handle and generation safeguards are promising, but the supplied execution evidence does not establish their final-effect behavior for guest replacement or stale-session attempts through this gateway path.
• Resolve merge risk (P1) - The new gateway exchange performs host-authority filesystem operations in guest-writable storage; rejection of workspace replacement and stale generations has not been demonstrated through this production entrypoint.
• Resolve merge risk (P1) - The package-upgrade evidence retains LocalState but does not show saved gateway port and working-directory settings being consumed afterward; an update could leave the gateway refusing startup or using unexpected settings.
• Complete next step (P2) - Add the authority and saved-settings evidence described above. Terminal output or redacted logs are appropriate; screenshots or recordings help when they show the relevant observations. Remove private endpoints, IP addresses, credentials, and personal details. Updating the PR body should trigger review automatically; otherwise ask a maintainer to comment @clawsweeper re-review.

Findings

• [medium] Verify guest rejection before host filesystem effects — src/OpenClaw.Launcher/Gateway/SessionGatewayClient.cs:133

Agent review details

Security

Needs attention: No exploitable defect was established, but the introduced gateway filesystem boundary still needs adversarial production-path evidence.

Review metrics

Metric	Value	Why it matters
Production versus test growth	production +2,998 net; tests +2,041 net	The growth implements the stated detached supervision, ownership inspection, persistence, and command surface.

Merge-risk options

Maintainer options:

1. Complete the two remaining proof checks (recommended)
   Show gateway exchanges rejecting guest redirection and stale generations before host effects, and show fresh defaults and saved settings working across a package update.
2. Hold this stack layer
   Keep the gateway layer pending until its authority and configuration contracts have the required evidence.

Technical review

Best possible solution:

Retain the scoped lifecycle design and establish gateway-boundary containment plus fresh-install and saved-settings upgrade behavior before landing.

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

Not applicable: this adds gateway-management capability; no concrete current-main bug or blocking introduced defect was established.

Is this the best way to solve the issue?

Yes, the scoped guest supervisor and identity-checked lifecycle fit the package’s external-supervision model; acceptance still depends on the identified authority and upgrade evidence.

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 Windows gateway-management feature without evidence of an urgent shipped regression.
• merge-risk: 🚨 security-boundary: New gateway exchanges cross from host authority into guest-writable storage without complete adversarial final-effect evidence.
• merge-risk: 🚨 compatibility: The new persisted gateway configuration needs evidence that saved values remain usable after a package update.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows MXC evidence supports detached launch, but does not show allowed gateway exchanges alongside rejection of guest workspace replacement and stale generations before host file effects. This scoped requirement applies despite the collaborator exemption from unrelated runtime proof; shared-helper and mocked gateway tests are supplemental. 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] Verify guest rejection before host filesystem effects — src/OpenClaw.Launcher/Gateway/SessionGatewayClient.cs:133
  Gateway requests, result reads, and cleanup use a guest-writable workspace under host authority. Existing handle and generation safeguards are promising, but the supplied execution evidence does not establish their final-effect behavior for guest replacement or stale-session attempts through this gateway path.
  Confidence: 0.85

What I checked:

• Verified review boundary: The local introduced delta matches the supplied 28-file merge-base-to-head boundary: 5,100 additions and 61 deletions. The supplied test merge is stale and was not used to claim that merging removes default-branch behavior. (056de40546c2)
• Still necessary on the default branch: The default-branch command tree exposes setup rather than isolated gateway lifecycle controls. Its README describes isolated-session execution as future work; the supplied related PRs remain open, not merged replacements. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs:47, 685ee93b7ebb)
• Release boundary: The latest supplied release, v2026.9.4-msix.0, points at the inspected default-branch revision without these controls. (685ee93b7ebb)
• Introduced authority boundary: Gateway start and inspection create host-written requests in the guest-writable workspace, execute them through IMxcSessionClient, read results, and clean up. The production runtime supplies a sandbox-and-generation validator. This establishes the MXC dependency and the specific cross-account filesystem boundary requiring assessment. (src/OpenClaw.Launcher/Gateway/SessionGatewayClient.cs:133, 056de40546c2)
• Containment safeguards and supplemental coverage: The inherited workspace implementation checks the current generation and uses handle-bound creation and deletion. Its relocation test retains directory authority through the write; the attached executor has a stale-generation no-write test. These support the safeguards but do not exercise the new gateway exchange with an adversarial guest through MXC. (src/OpenClaw.Launcher/Session/SessionWorkspaceOperation.cs:73, 056de40546c2)
• Process ownership before termination: Termination retains a process handle, checks exact creation time and helper image, and kills that verified process rather than enumerating potentially reused child identifiers. Tests exercise wrong-time and wrong-image rejection against real processes. (src/OpenClaw.SessionHost/SessionTerminator.cs:47, 056de40546c2)

Likely related people:

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

Rank-up moves

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

• Provide redacted production-boundary output showing allowed gateway exchanges and rejection of guest workspace replacement or stale generations before host file effects.
• Show fresh-record defaults and saved port and working-directory settings being consumed after a package update.

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

• reviewed 2026-09-17T16:33:13.218Z sha 6d75843 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T16:38:13.998Z sha 6d75843 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T16:56:30.720Z sha 6d75843 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T17:05:35.679Z sha 6d75843 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T18:19:38.329Z sha 8d98367 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T19:00:45.725Z sha 16673a8 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T19:22:46.062Z sha eb2fdba :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T19:40:43.556Z sha eb2fdba :: needs real behavior proof before merge. :: none