Improve clawctl output readability and color

[paulcam206]

Summary

• separate clawctl operations from presentation with semantic result records
• render consistent human-readable output with Spectre.Console
• add capability-aware color handling for --no-color, NO_COLOR, FORCE_COLOR, CI, and redirected streams
• expand status and diagnostic output while keeping routine implementation details out of the user experience

Review

A committed-range code review found and fixed three user-visible issues before publication:

• setup --no-isolation now reports that Node.js was installed in the host rather than an isolated session
• stopping an absent gateway no longer recommends starting it
• stderr interactivity and Unicode/color capability are determined from stderr rather than stdout

Regression coverage was added for each issue.

Validation

Validated at 62779b686ca5f3f6be5253675a4c8776590e0a3c:

• .\scripts\Test-DotNetQuality.ps1
• dotnet test .\OpenClaw.Gateway.MSIX.slnx --configuration Release --no-restore — 667 passed
• .\scripts\Test-NativeAotCli.Tests.ps1 — 14 NativeAOT scenarios passed

[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: blocked before merge. Reviewed September 17, 2026, 8:51 PM ET / September 18, 2026, 00:51 UTC (Revision 7).

ClawSweeper review

What this changes

The PR centralizes clawctl rendering, adds terminal-aware color and progress output, expands status reporting, preserves reset diagnostics, and handles interrupted commands.

Merge readiness

⛔ Blocked before merge - 3 items remain

The previous code findings are resolved, and the contribution remains distinct from main. The status exit-code compatibility choice and outdated PR description still need resolution.

Priority: P2
Reviewed head: e75e35673430449e81524a1ebd77072689e1d70f
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The implementation has focused regression coverage and resolves prior findings; compatibility intent and the durable validation description remain open.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored PR is exempt from ordinary contributor runtime proof. The captured native and unit validation targets an older revision; no current interactive Windows behavior is claimed here.
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 runtime proof. The captured native and unit validation targets an older revision; no current interactive Windows behavior is claimed here.
Evidence reviewed	7 items	Repository policy: No root or nested AGENTS.md or maintainer-notes directory was found. CONTRIBUTING.md requires an accurate description, validation revision, and disclosure of unrun validation lanes. Still distinct from released main: The pinned main revision retains the small plain-text renderer and session-only status exit calculation. The local v2026.9.4-msix.1 tag points to that main revision; the requested rendering changes are absent there. Prior teardown finding fixed: The renderer now emits nonempty details after successful teardown, and SuccessfulTeardownPreservesStopFailureDetail covers the reported case. Comparing GitHub’s pinned previous file contents with the checkout confirmed these additions.
Findings	None	None.
Security	None	None.

How this fits together

clawctl manages the Windows package’s isolated session, bundled runtime, gateway, and sign-in recovery. Management commands produce operation results that the new renderer turns into terminal output and exit codes.

flowchart TD
  A[Management command] --> B[Command parsing]
  B --> C[Session and gateway operations]
  C --> D[Operation results]
  E[Terminal capabilities and color settings] --> F[Output renderer]
  D --> F
  F --> G[Readable terminal output]
  D --> H[Process exit code]

Loading

Decision needed

Question	Recommendation
Should clawctl status retain its session-only exit contract or intentionally become an aggregate session, gateway, and recovery health check?	Preserve the existing exit contract: Display the additional gateway and recovery diagnostics while retaining session-based success and failure codes.

Why: Both interpretations are coherent, but the broader failure conditions change existing automation and are not explicitly resolved in the captured discussion or documentation.

Before merge

• Resolve merge risk (P1) - Existing automation using clawctl status as a session-health check can begin failing after upgrade because gateway or sign-in recovery problems now independently produce exit code 1; acceptance and fresh/existing-installation coverage remain unclear.
• Complete next step (P2) - Resolve and document the status exit-code contract with fresh/existing-installation coverage, then refresh the PR body’s obsolete setup claims and validation revision.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +1,239 net lines; tests +878 net lines	The stated justification is centralized rendering, richer diagnostics, and regression coverage across lifecycle output.

Merge-risk options

Maintainer options:

1. Keep status compatible (recommended)
   Preserve the old exit calculation while retaining the expanded human-readable diagnostics.
2. Adopt the broader contract explicitly
   Approve the additional failure conditions with documented upgrade behavior and focused fresh/existing-installation checks.

Technical review

Best possible solution:

Keep the unified renderer while preserving the existing status exit contract unless maintainers explicitly adopt and document aggregate health semantics with fresh-install and upgrade coverage.

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

Not applicable to the readability feature. The status exit-code difference is directly established by source comparison; no runtime tests were executed during this read-only review.

Is this the best way to solve the issue?

Yes for centralized rendering and capability-aware color; unclear for expanding status failure semantics without an explicit compatibility contract.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a bounded CLI usability improvement with an exit-code compatibility choice.
• merge-risk: 🚨 compatibility: A healthy session can now yield status exit code 1 because of gateway or recovery state, changing existing callers’ behavior.
• 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 runtime proof. The captured native and unit validation targets an older revision; no current interactive Windows behavior is claimed here.

Evidence

What I checked:

• Repository policy: No root or nested AGENTS.md or maintainer-notes directory was found. CONTRIBUTING.md requires an accurate description, validation revision, and disclosure of unrun validation lanes. (CONTRIBUTING.md:228, e75e35673430)
• Still distinct from released main: The pinned main revision retains the small plain-text renderer and session-only status exit calculation. The local v2026.9.4-msix.1 tag points to that main revision; the requested rendering changes are absent there. (src/OpenClaw.Launcher/ClawCtlConsole.cs:5, ad5df933da4f)
• Prior teardown finding fixed: The renderer now emits nonempty details after successful teardown, and SuccessfulTeardownPreservesStopFailureDetail covers the reported case. Comparing GitHub’s pinned previous file contents with the checkout confirmed these additions. (src/OpenClaw.Launcher/ClawCtlConsole.cs:379, e75e35673430)
• Earlier fixes retained: Reset reports retain previous snapshots and are restored after cleanup; regression coverage exercises two resets with the production cleaner and subsequent bundle collection. The last-chance failure renderer guards unavailable writers, with focused startup coverage. (tests/OpenClaw.Launcher.Tests/ProgramTests.cs:697, e75e35673430)
• Status compatibility remains unresolved: Main derives status success only from session availability. The PR additionally returns 1 for unhealthy or unknown gateways and action-required or unknown recovery. The added command test covers ready recovery and an unstarted gateway, but does not establish the fresh/existing-installation failure matrix or document this exit-code change. (src/OpenClaw.Launcher/ClawCtlResults.cs:47, e75e35673430)
• Captured validation context: The supplied PR body attributes 667 tests and 14 NativeAOT scenarios to 62779b6 and still describes setup --no-isolation. Main removed that mode. The captured author association is COLLABORATOR, so ordinary external-contributor runtime proof is not required. (62779b686ca5)

Likely related people:

• Paul Campbell: Raw commit 8d98d48 adds src/OpenClaw.Launcher/WindowsHostConsole.cs:72 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 8d98d48a5a2f; files: src/OpenClaw.Launcher/WindowsHostConsole.cs)

Rank-up moves

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

• Resolve the status exit contract, document it, and cover fresh and existing installation states.
• Refresh the PR description to remove obsolete no-isolation claims and identify current validation revisions and unrun lanes.

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 (6 earlier review cycles)

• reviewed 2026-09-17T20:44:02.360Z sha 62779b6 :: blocked before merge. :: [P1] Preserve the pre-reset report outside the cleanup boundary | [P2] Carry forced-cleanup warnings through failed setup results | [P2] Track runtime location separately from session readiness
• reviewed 2026-09-17T20:48:49.057Z sha 62779b6 :: blocked before merge. :: [P1] Preserve the pre-reset report outside the cleanup boundary | [P2] Carry forced-cleanup warnings through failed setup results | [P2] Track runtime location separately from session readiness
• reviewed 2026-09-17T21:29:58.466Z sha 737af0b :: blocked before merge. :: [P2] Preserve earlier residual identifiers across repeated resets
• reviewed 2026-09-17T22:26:50.763Z sha 42c3f83 :: blocked before merge. :: [P2] Preserve earlier residual identifiers across repeated resets | [P2] Guard writes from the last-chance error renderer
• reviewed 2026-09-17T23:37:38.542Z sha d3819c9 :: blocked before merge. :: [P2] Preserve earlier residual identifiers across repeated resets | [P2] Guard writes from the last-chance error renderer
• reviewed 2026-09-18T00:28:13.688Z sha c74c314 :: blocked before merge. :: [P2] Preserve stop-failure details after successful deprovision