improve: restore terminal state and standardize the OpenClaw runtime environment

[paulcam206]

What Problem This Solves

Windows console state can be left altered after a child process runs, and launcher environment decisions were scattered. That makes terminal behavior inconsistent before the isolated-session work has a stable host foundation.

User Impact

Terminal users get console mode and encoding restored around child execution, plus consistent color and interactivity decisions. This is independently useful host behavior; it does not create or route an isolated session yet.

Why This Change Was Made

WindowsHostConsole captures and restores the Windows console mode and encoding around a child process so the launcher does not leak its terminal changes back to the caller.

OpenClawRuntimeEnvironment centralizes the FORCE_COLOR, WT_SESSION, and NO_COLOR rules and interactive detection. Later layers can build on one environment contract instead of duplicating terminal heuristics.

The stack’s end goal is an owned isolated Windows agent session that can run openclaw, an interactive PowerShell entry point, a supervised gateway, sign-in recovery, redacted diagnostics, safe teardown, and runnable local deployment. This layer deliberately remains the smallest independently useful slice: it establishes stable host behavior without introducing MXC, session state, or a new account/profile.

Review fixes addressed

Review found no blocking defect. This revision also tolerates UTF-8 encoding initialization when console handles are redirected; the attached MXC integration in #44 initializes UTF-8 inside the existing capture/restore lifetime.

Current validation

Current layer head: 5a879fca143aed40e0e847dff21cae515a50aefa. 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 1 of 12. Parent: main

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

ClawSweeper review

What this changes

Adds reusable Windows console restoration and runtime-environment helpers, twelve unit tests, and test-scoped analyzer exceptions, with production integration deferred to later stack layers.

Merge readiness

✅ Ready for maintainer review

This remains useful stack groundwork that is absent from main. No blocking introduced defect was found; the current head also has an approving collaborator review.

Likely related people: paulcam206 and anna-dingler, as launcher-area routing candidates.

Priority: P2
Reviewed head: 5a879fca143aed40e0e847dff21cae515a50aefa

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, tested foundation with no blocking correctness finding; runtime integration belongs to the dependent stack.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored PR is exempt from ordinary contributor proof, and this layer introduces no material authority change. Integrated Windows runs provide context, but version and status output alone do not establish console restoration coverage.
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 PR is exempt from ordinary contributor proof, and this layer introduces no material authority change. Integrated Windows runs provide context, but version and status output alone do not establish console restoration coverage.
Evidence reviewed	8 items	Verified scope and repository policy: The origin identifies the target repository. No root or nested AGENTS.md or maintainer-notes directory was found. The pinned main-to-head diff contains exactly the five supplied paths. Console restoration implementation: Capture records modes, native code pages, and managed encodings; disposal is idempotent, enables processed output and virtual-terminal processing for cleanup, and restores managed encodings before native code pages. Tests cover restoration, redirected output, and encoding-setter failures. Environment precedence and integration boundary: The helper preserves explicitly supplied terminal and diagnostic values before adding defaults. Current production launch code still sets the three lifecycle variables directly; only tests reference the new helpers. The linked next layer explicitly owns attached-console integration.
Findings	None	None.
Security	None	None.

How this fits together

The Windows package launcher starts the bundled OpenClaw runtime. These helpers prepare child-process environment values and capture and restore the caller’s console state; this layer does not yet connect them to launcher execution.

flowchart TD
  A[Caller environment] --> B[Runtime environment helper]
  C[Interactive or detached context] --> B
  B --> D[Child environment values]
  E[Windows console state] --> F[Console capture helper]
  F --> G[UTF-8 initialization]
  G --> H[Dispose and restore console]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +436, tests +338; configuration +17	Production growth is justified as shared stack groundwork, although this layer has no production callers.
Focused regression coverage	12 added tests	Eight environment tests and four console tests cover precedence, restoration, redirection, and encoding failures.

Technical review

Best possible solution:

Keep one shared console and environment contract, with its production callers introduced and validated in the dependent stack layers.

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

Not applicable to a blocking patch defect: none was identified. The proposed helpers are not called by production in this layer, and Windows runtime behavior was not executed during this review.

Is this the best way to solve the issue?

Yes, as a preparatory stack layer: the helpers provide a focused reusable boundary, preserve explicit environment values, and leave activation to the linked integration work.

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 launcher reliability improvement without an established urgent production 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 PR is exempt from ordinary contributor proof, and this layer introduces no material authority change. Integrated Windows runs provide context, but version and status output alone do not establish console restoration coverage.

Evidence

What I checked:

• Verified scope and repository policy: The origin identifies the target repository. No root or nested AGENTS.md or maintainer-notes directory was found. The pinned main-to-head diff contains exactly the five supplied paths. (5a879fca143a)
• Console restoration implementation: Capture records modes, native code pages, and managed encodings; disposal is idempotent, enables processed output and virtual-terminal processing for cleanup, and restores managed encodings before native code pages. Tests cover restoration, redirected output, and encoding-setter failures. (src/OpenClaw.Launcher/WindowsHostConsole.cs:165, 5a879fca143a)
• Environment precedence and integration boundary: The helper preserves explicitly supplied terminal and diagnostic values before adding defaults. Current production launch code still sets the three lifecycle variables directly; only tests reference the new helpers. The linked next layer explicitly owns attached-console integration. (src/OpenClaw.Launcher/OpenClawRuntimeEnvironment.cs:47, 5a879fca143a)
• Main and release necessity check: Main retains the existing direct environment assignments and has no console-mode restoration or terminal-hint implementation matching this change. The supplied latest release is at this same main revision, locally tagged v2026.9.4-msix.0; no merged replacement was established. (src/OpenClaw.Launcher/GatewayLauncher.cs:73, 685ee93b7ebb)
• Review discussion and continuity: anna-dingler approved the pinned head on September 17. Her comments concern clarification, logging, and file organization. xlinush's explicitly non-blocking processed-output suggestion is implemented. The previous completed ClawSweeper review covers the same head and records no findings or published rank-up moves. (5a879fca143a)
• Launcher history routing: The path history identifies prior launcher work by Paul Campbell, Anna Koenig, and Linus Huang. GitHub commit reads verified paulcam206's asynchronous child-wait changes and anna-dingler's packaged-execution changes. Older local history traversal and blame stopped at unavailable objects, so no introducing-author claim is made. (src/OpenClaw.Launcher/GatewayLauncher.cs, 2904bd8dd641)

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.

History

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

• reviewed 2026-09-17T01:52:41.356Z sha 72fb92c :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:10:40.744Z sha 5a879fc :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T16:22:39.779Z sha 5a879fc :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T17:03:58.718Z sha 5a879fc :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T18:18:15.896Z sha 5a879fc :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:00:12.537Z sha 5a879fc :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:21:47.111Z sha 5a879fc :: needs maintainer review before merge. :: none
• reviewed 2026-09-17T19:39:20.414Z sha 5a879fc :: needs maintainer review before merge. :: none

[xlinush]

[Linus's bot] Could we also enable ENABLE_PROCESSED_OUTPUT alongside ENABLE_VIRTUAL_TERMINAL_PROCESSING before writing the cleanup escape sequence? Microsoft's SetConsoleMode docs explicitly say: "Ensure ENABLE_PROCESSED_OUTPUT is set when using this flag."

Normal consoles already have it enabled; setting both here would cover a child clearing it before exit. Small defensive hardening suggestion, not a blocker.

[anna-dingler]

nit: Is it intentional that we aren't applying the currentValue if its present? I see if the logic above that we only apply our default values after currentValue has been applied and perf == 1. Maybe a comment about the conditional would add clarity, or combining the AddIfPresent and AddDefault methods

[anna-dingler]

Should we be handling/logging the errors here?

[anna-dingler]

nit: In case we have more imports later, it could make sense to put this class in its own file.