feat: open an interactive shell inside the isolated agent session

[paulcam206]

What Problem This Solves

After setup, an operator needs an interactive shell in the isolated agent session where typing openclaw resolves to that session rather than the host.

User Impact

clawctl pwsh opens an interactive agent shell. It prefers PowerShell 7 and falls back to Windows PowerShell, while preserving the interactive environment.

Why This Change Was Made

clawctl pwsh launches the available PowerShell inside the session, choosing PowerShell 7 first and Windows PowerShell only when necessary.

An ASCII openclaw.cmd shim makes the openclaw command resolve inside the session without relying on non-ASCII command-file behavior. The shell keeps the interactive environment established by the host.

This layer is an interactive entry point only. It does not supervise the gateway, register logon recovery, or collect diagnostics.

Review fixes addressed

Guest-controlled destination can redirect a host write (high). The agent command shim was written by the host into the shared workspace, which the guest also controls. Validating the path and then writing to it by name left the checked object and the written object distinct, so a directory swapped in between could redirect a host-account write.

The shim is no longer written by the host. openclaw-session-host --install-tools creates it from inside the agent account, over a typed request/result pair (SessionToolInstallRequest / SessionToolInstallResult) carried through the shared workspace like every other guest operation. AgentToolShim now only builds the environment the shim consumes, and the host verifies the returned shim path before using it. The host no longer writes into guest-controlled storage at all, so there is no validation-to-use window left to lose.

Current validation

Latest hosted follow-up: The shell entry point now validates the installed agent runtime against the packaged archive path, matching the RequireAgentNodePath contract; the independent layer and final stack tip compile cleanly under the pinned SDK.

Current layer head: 6fad787ca300e2437fd359d3aa3cec1b05e37061. 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 5 of 12. Parent: #46 - feat/session-isolated-lifecycle

[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 29).

ClawSweeper review

What this changes

Adds clawctl pwsh to open PowerShell in the isolated agent account with the packaged Node runtime and a guest-installed openclaw command shim.

Merge readiness

✅ Ready for maintainer review

This remains a useful, distinct addition absent from current main and the latest release. The prior runtime-resolution and host-write concerns are addressed; no blocking introduced defect was identified. Collaborator-authored work is protected from automatic closure.

Priority: P2
Reviewed head: 6fad787ca300e2437fd359d3aa3cec1b05e37061

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with relevant regression coverage and resolved prior concerns; runtime validation claims were inspected but not independently executed.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator exemption applies: supplied integrated version/status and installation results do not directly exercise RunPowerShellAsync's interactive shell, but no additional authority-chain proof gate is warranted by the reviewed change.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator exemption applies: supplied integrated version/status and installation results do not directly exercise RunPowerShellAsync's interactive shell, but no additional authority-chain proof gate is warranted by the reviewed change.
Evidence reviewed	7 items	Current main and release lack the shell command: The current-main command tree exposes setup but no pwsh command; the supplied latest release points to this same commit. A broader source/test/README search found no interactive-shell implementation. Prior runtime-resolution finding addressed: RunPowerShellAsync supplies GetPackagedNodeArchivePath to RequireAgentNodePath, matching the existing archive-identity contract. Added tests cover a ready session and rejection of a different architecture's archive. Guest-side shim write preserves the principal boundary: The new installer writes openclaw.cmd inside the guest helper. Host request/result operations use SessionWorkspaceOperation, with generation checks and handle-bound file operations. The returned shim directory is escaped into guest PowerShell arguments; it does not authorize a host-side shim write. The body overstates containment validation of the returned path, but that path is consumed under guest authority.
Findings	None	None.
Security	None	None.

How this fits together

The Windows package launcher connects operator commands to an owned isolated agent session. This entry point uses the existing session transport to install the command shim and run an interactive shell under the guest identity.

flowchart TD
 A[Operator invokes clawctl pwsh] --> B[Check setup and recorded session]
 B --> C[Resolve packaged runtime and helper]
 C --> D[Install command shim as guest]
 D --> E[Select available PowerShell]
 E --> F[Run attached shell in agent account]
 F --> G[Return shell exit code]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +379 net lines; tests +248 net lines	The growth implements the stated shell entry point, guest installer, protocol, and focused coverage across 16 files.

Technical review

Best possible solution:

Keep the shell as a thin consumer of the owned-session execution path, with command installation and execution confined to the guest account.

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

Not applicable: this adds an interactive-shell capability rather than reporting a current-main bug; no Windows execution was performed during this read-only review.

Is this the best way to solve the issue?

Yes: extending the existing command tree and guest execution transport is a focused approach, and guest-side shim installation addresses the earlier host-authority concern.

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 operator capability for the isolated-session stack, without an established urgent user-facing 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 exemption applies: supplied integrated version/status and installation results do not directly exercise RunPowerShellAsync's interactive shell, but no additional authority-chain proof gate is warranted by the reviewed change.

Evidence

What I checked:

• Current main and release lack the shell command: The current-main command tree exposes setup but no pwsh command; the supplied latest release points to this same commit. A broader source/test/README search found no interactive-shell implementation. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs:40, 685ee93b7ebb)
• Prior runtime-resolution finding addressed: RunPowerShellAsync supplies GetPackagedNodeArchivePath to RequireAgentNodePath, matching the existing archive-identity contract. Added tests cover a ready session and rejection of a different architecture's archive. (src/OpenClaw.Launcher/Program.cs:396, 6fad787ca300)
• Guest-side shim write preserves the principal boundary: The new installer writes openclaw.cmd inside the guest helper. Host request/result operations use SessionWorkspaceOperation, with generation checks and handle-bound file operations. The returned shim directory is escaped into guest PowerShell arguments; it does not authorize a host-side shim write. The body overstates containment validation of the returned path, but that path is consumed under guest authority. (src/OpenClaw.SessionHost/SessionToolInstaller.cs:36, 6fad787ca300)
• Review continuity and comparison limits: The supplied previous completed review contains no findings or published rank-up moves. The retained earlier archive-resolver finding is resolved in current source. The earlier reviewed commit could not be loaded locally, so no claim of unchanged code or late-discovered introduction is made. The host marks the test merge stale; it was not used to infer removal of main-branch behavior. (6fad787ca300)
• Captured validation and proof scope: The supplied complete PR body reports integrated NativeAOT builds, 642 passing tests, live packaged version/status results, and signed fresh-install/upgrade checks. These results support the surrounding stack but do not directly demonstrate interactive pwsh input, guest command resolution, or shell exit. The author is a COLLABORATOR, so ordinary contributor proof is exempt. No unresolved introduced authority violation was established that would activate the scoped proof exception. (6fad787ca300)
• Distinct stack dependency: The supplied discussion identifies feat: run OpenClaw in an owned isolated agent session #46 as the open lifecycle parent and feat: manage the OpenClaw gateway inside the isolated session #48 as the gateway-management child. Neither replaces this shell entry point.

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)

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

• reviewed 2026-09-17T16:32:29.167Z sha 9ef2813 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T16:39:07.430Z sha 9ef2813 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:55:40.823Z sha 9ef2813 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T17:04:57.012Z sha 9ef2813 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T18:18:47.229Z sha f3caf03 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:00:21.603Z sha 72eea89 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:22:04.016Z sha e01efa2 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:40:16.468Z sha e01efa2 :: needs maintainer review before merge. :: none