feat/clawctl json

[paulcam206]

Impact

Adds --json to every non-interactive clawctl command, with one versioned document on stdout and stable nonzero exit codes for failures.

Why This Change Was Made

Automation should consume a typed contract rather than parse human-oriented output. Failure documents preserve the selected command, status failures retain their state details, and teardown confirmation produces valid JSON.

Evidence

Validated at 95dc7ac:

• .\scripts\Test-DotNetQuality.ps1
• Focused JSON failure-contract tests: 5 passed
• .\scripts\Test-NativeAotCli.Tests.ps1: 17 intended scenarios passed
• GitHub CI runs on the current head

Stack

1. feat/clawctl json #69 JSON (this PR)
2. feat: render clawctl help from the live command tree #70 dynamic help
3. feat: report the package and payload build identity from clawctl --version #71 build identity
4. feat: wait for the gateway and report where it is listening #72 narrated gateway startup

[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 18, 2026, 12:35 AM ET / 04:35 UTC (Revision 5).

ClawSweeper review

What this changes

Adds opt-in, versioned JSON output for clawctl management commands, including structured failures, color suppression, documentation, and regression coverage.

Merge readiness

✅ Ready for maintainer review

The JSON capability remains absent from main and the latest release. All five earlier findings are addressed, and no new blocking defect was found.

Likely related people: paulcam206 (high-confidence routing from prior merged launcher work).

Priority: P2
Reviewed head: 95dc7ac47dacc39eea1d189f569a31648c3983bb

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with relevant regression coverage and all earlier findings resolved.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored PR is exempt from the external-contributor proof gate. Reported tests cover launcher JSON failures and NativeAOT serialization; installed-package behavior was not independently verified.
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 the external-contributor proof gate. Reported tests cover launcher JSON failures and NativeAOT serialization; installed-package behavior was not independently verified.
Evidence reviewed	7 items	Policy and checkout inspection: Verified the origin repository. No root or nested AGENTS.md or maintainer-notes directory was found. The checkout remained clean, and the introduced diff passed git diff --check. Bounded presentation change: The complete introduced diff routes existing command results through explicit JSON DTOs and source-generated serialization. JSON setup suppresses progress narration; ordinary output and operation exit codes retain their existing paths. Earlier findings resolved: Status JSON derives success from the existing ExitCode contract and retains state details; teardown refusal emits JSON; unexpected failures preserve command selection; parsed boolean values reach the outer handler; JSON mode is initialized before package discovery. Focused regression tests cover these paths. The latest completed review inspected this same head and reported no findings.
Findings	None	None.
Security	None	None.

How this fits together

clawctl manages the Windows package’s isolated session, runtime, gateway, and diagnostics. This change converts management results into JSON for scripts while preserving the existing human output by default.

flowchart TD
  A[Management command] --> B[Parse output option]
  B --> C[Existing session and gateway operations]
  C --> D[Command result]
  D --> E{JSON requested?}
  E --> F[Versioned JSON on stdout]
  E --> G[Human-readable output]
  D --> H[Existing exit code]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test LOC	Production +424/-61; tests +319/-3	Production growth implements the stated versioned serialization contract, with regression and NativeAOT coverage alongside it.

Technical review

Best possible solution:

Keep machine output as an opt-in, versioned projection of existing command results, with human presentation and lifecycle behavior preserved.

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

Not applicable: this adds an output mode rather than reporting an existing-behavior bug; source inspection confirms main lacks that mode.

Is this the best way to solve the issue?

Yes. Reusing semantic command results with explicit, source-generated DTOs is a focused approach that separates the machine contract from human formatting and supports NativeAOT.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a bounded automation improvement to Windows package management commands.
• 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 the external-contributor proof gate. Reported tests cover launcher JSON failures and NativeAOT serialization; installed-package behavior was not independently verified.

Evidence

What I checked:

• Policy and checkout inspection: Verified the origin repository. No root or nested AGENTS.md or maintainer-notes directory was found. The checkout remained clean, and the introduced diff passed git diff --check. (95dc7ac47dac)
• Bounded presentation change: The complete introduced diff routes existing command results through explicit JSON DTOs and source-generated serialization. JSON setup suppresses progress narration; ordinary output and operation exit codes retain their existing paths. (src/OpenClaw.Launcher/ClawCtlJson.cs:39, 95dc7ac47dac)
• Earlier findings resolved: Status JSON derives success from the existing ExitCode contract and retains state details; teardown refusal emits JSON; unexpected failures preserve command selection; parsed boolean values reach the outer handler; JSON mode is initialized before package discovery. Focused regression tests cover these paths. The latest completed review inspected this same head and reported no findings. (src/OpenClaw.Launcher/Program.cs:33, 95dc7ac47dac)
• Still necessary on current main: GitHub confirms main remains at the pinned base. Its command tree has no JSON option. The merged presentation work at Improve clawctl output readability and color #66 supplies semantic results but does not implement this capability. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs:67, b904c90c1439)
• Latest release lacks JSON support: GitHub identifies v2026.9.4-msix.1 as the latest release at ad5df93. Its command tree also lacks the JSON option; the release source was read through GitHub after the local historical blob read failed. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs, ad5df933da4f)
• Merged feature-history routing: Recent launcher history repeatedly identifies Paul Campbell. The semantic result file was added by b904c90; its raw recorded parent is ad5df93, where that path is absent. Provided merged-PR metadata connects this prior work to paulcam206 independently of the current proposal. (src/OpenClaw.Launcher/ClawCtlResults.cs:47, b904c90c1439)

Likely related people:

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

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

• reviewed 2026-09-18T01:10:15.232Z sha a6f47a4 :: needs changes before merge. :: [P2] Derive status success from the existing failure semantics | [P2] Emit a JSON failure when teardown requires confirmation | [P2] Preserve the selected command in unexpected-failure documents
• reviewed 2026-09-18T01:54:11.281Z sha a5bbc3e :: needs changes before merge. :: [P2] Use parsed JSON option values in the outer failure handler
• reviewed 2026-09-18T02:09:24.135Z sha ceb7b20 :: needs changes before merge. :: [P2] Resolve JSON mode before package discovery can fail
• reviewed 2026-09-18T02:35:12.305Z sha 95dc7ac :: needs maintainer review before merge. :: none