docs: document the isolated session runtime

[paulcam206]

What Problem This Solves

Operators and maintainers need documentation that matches the implemented isolated-session lifecycle and clearly distinguishes host and guest behavior.

User Impact

The README makes lifecycle commands discoverable, and the MXC compatibility evidence explains the backend seam and ownership model that maintain the session boundary.

Why This Change Was Made

The documentation describes the implemented runtime without claiming a published MXC SDK, changing command semantics, or making local Developer Mode deployment runnable.

Documentation corrections

• Distinguishes on-demand direct-host Node extraction from setup's agent-profile runtime installation.
• Describes clawctl status as session-only and directs gateway-state checks to clawctl gateway-service status.
• Aligns setup, recovery, diagnostics, teardown, and reset documentation with their current command boundaries and deferred work.

Current validation

Current layer head: 753d8c5b275cf0db80f86cd3d960320cdf2c395a. 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 11 of 12. Parent: #52 - feat/session-fresh-reset. Child: #54 - improve/session-local-deployment

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

ClawSweeper review

What this changes

Expands the README command reference and adds an operational guide covering isolated sessions, host execution, gateway management, diagnostics, and cleanup.

Merge readiness

✅ Ready for maintainer review

Keep open: this remains useful documentation for the pending session stack, and no introduced blocking defect was found. The default branch and latest release do not contain this guide.

Priority: P3
Reviewed head: 753d8c5b275cf0db80f86cd3d960320cdf2c395a

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused documentation update whose central operational claims agree with the pinned implementation.
Proof confidence	🌊 off-meta tidepool	Not applicable: This collaborator-authored documentation patch has no changed production behavior requiring runtime proof; the body’s integrated Windows validation is supporting context, not independent proof of every documented guarantee.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This collaborator-authored documentation patch has no changed production behavior requiring runtime proof; the body’s integrated Windows validation is supporting context, not independent proof of every documented guarantee.
Evidence reviewed	9 items	Verified documentation-only introduction: The pinned base-to-head delta contains only README.md and the new operational guide: 173 added and 7 removed documentation lines, with no production, test, dependency, or workflow changes. Host and guest setup claims match source: Direct execution supplies NodeRuntimeInstaller.EnsureInstalled; the host-only setup branch prepares the host runtime, while RunSetupCoreAsync installs the guest runtime and configures recovery without launching a gateway. Status probe and reset semantics checked: ProbeRecordedStatusAsync starts the recorded provision without replacing it; focused tests assert this behavior. ProgramTests also cover stopping an ordinary fresh reset before deletion when teardown fails and preserving warnings during forced cleanup.
Findings	None	None.
Security	None	None.

How this fits together

The Windows package launcher routes OpenClaw commands to the host or an owned isolated agent session. Its separate clawctl commands prepare runtimes, manage the session and gateway, and collect diagnostics.

flowchart TD
  A[Operator commands] --> B[Windows package launcher]
  B --> C[Host or isolated session selection]
  C --> D[Host runtime]
  C --> E[Owned agent session]
  B --> F[Setup and lifecycle management]
  F --> E
  E --> G[OpenClaw CLI and gateway]
  D --> G

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep this operator guide alongside the corresponding session implementation as the stack lands in dependency order.

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

Not applicable: this PR changes documentation; its command and lifecycle claims were checked against the pinned source and focused tests without executing them.

Is this the best way to solve the issue?

Yes: a concise README reference linked to a dedicated operational guide is a bounded way to explain the implemented stack without changing command semantics.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P3: This is documentation for the session stack with no executable behavior changes.
• 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: This collaborator-authored documentation patch has no changed production behavior requiring runtime proof; the body’s integrated Windows validation is supporting context, not independent proof of every documented guarantee.

Evidence

What I checked:

• Verified documentation-only introduction: The pinned base-to-head delta contains only README.md and the new operational guide: 173 added and 7 removed documentation lines, with no production, test, dependency, or workflow changes. (README.md:63, 753d8c5b275c)
• Host and guest setup claims match source: Direct execution supplies NodeRuntimeInstaller.EnsureInstalled; the host-only setup branch prepares the host runtime, while RunSetupCoreAsync installs the guest runtime and configures recovery without launching a gateway. (src/OpenClaw.Launcher/Program.cs:559, 753d8c5b275c)
• Status probe and reset semantics checked: ProbeRecordedStatusAsync starts the recorded provision without replacing it; focused tests assert this behavior. ProgramTests also cover stopping an ordinary fresh reset before deletion when teardown fails and preserving warnings during forced cleanup. (tests/OpenClaw.Launcher.Tests/Session/SessionCoordinatorTests.cs:59, 753d8c5b275c)
• Diagnostics claims match the collection boundary: The production collector names agent log and configuration sources explicitly, preserves host diagnostics when guest collection fails, and writes the documented best-effort redaction warning into the ZIP manifest. (src/OpenClaw.Launcher/Gateway/DiagnosticsBundle.cs:250, 753d8c5b275c)
• MXC implementation boundary: The new guide explicitly names the pinned MXC CLI dependency. The target adapter documents the same temporary CLI transport behind IMxcSessionClient; the prose does not establish any dependency on Codex Code Mode. (src/OpenClaw.Launcher/Mxc/MxcCliSessionClient.cs:41, 753d8c5b275c)
• Default branch and release still lack the guide: The fetched main README still describes isolated execution as future work and exposes only setup and version in its command table. Its docs tree lacks the new guide; the same commit carries v2026.9.4-msix.0. (README.md:49, 685ee93b7ebb)

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

• reviewed 2026-09-17T16:32:10.934Z sha 3ead480 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:37:56.941Z sha db008c9 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:55:41.592Z sha 9faacb9 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T17:05:04.017Z sha 9faacb9 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T18:20:06.784Z sha 7419c90 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:01:33.381Z sha 9c9059d :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:21:56.435Z sha d31bc96 :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:39:53.521Z sha e234e6c :: needs maintainer review before merge. :: none