fix: preserve isolated capability in clawctl error responses

[RomneyDa]

Problem and outcome

Related: openclaw/openclaw-windows-node#1672

clawctl status --json normally advertises integration.kind = isolated-session, version 1. Its operational exception boundary emits an error document without that package capability. Companion checks this capability before invoking package setup, so an exception can be misclassified as an unsupported package and prevent the existing automatic setup step.

Retain the same immutable capability in operational error responses. Preserve ok: false, the original error, command identity and nonzero exit code. Do not invent session readiness, listener ownership or credentials. Explicit package setup and all Companion success/credential checks remain unchanged.

Maintainer reproduction gate accepted (2026-10-07). The maintainer explicitly decided: "Accept bounded reproduction; keep original incident open." The controlled real lifecycle-contention comparison satisfies the reproduction gate for this bounded producer-contract repair. This is not a confirmed root cause or complete fix of the original Store incident. Its failing JSON was not retained, and a clean same-version retest passed. The exact reported wizard error was reproduced on the exact base; the PR candidate completed automatic onboarding under the same condition. Original incident cause and spontaneous retained-state reproduction remain unknown. Issue #1672 remains open and Related, not Fixes. No merge is authorized.

Ownership and risk

Old and new owner: ClawCtlJson.WriteFailure, the package-owned operational error envelope. No consumer workaround, new provisioning path, protocol version bump, package pin, or credential handoff change. Capability is not readiness or authorization.

Required proof pools

None from the Windows-node inventory: this PR changes packaging's JSON producer only. Relevant packaging lanes: quality, Release tests, NativeAOT CLI, and installed native Companion onboarding in an isolated Windows environment.

Validation

Head: c7d42f7.

• Regression on unchanged production code: all four strengthened ProgramStartupTests.JsonOperationalFailurePreservesTheSelectedCommandAndIntegration cases failed for missing integration metadata.
• macOS ARM64 focused suite: 23 passed, zero failed/skipped. Command: dotnet test tests/OpenClaw.Launcher.Tests/OpenClaw.Launcher.Tests.csproj --configuration Release -p:EnableWindowsTargeting=true --no-restore --filter "FullyQualifiedName~JsonOperationalFailurePreservesTheSelectedCommandAndIntegration|FullyQualifiedName~ClawCtlReadinessOutputTests" --verbosity quiet.
• Canonical quality gate: EnableWindowsTargeting=true pwsh -NoProfile -File scripts/Test-DotNetQuality.ps1 passed, zero build warnings/errors, whitespace and style verification passed.
• pwsh -NoProfile -File scripts/Test-DocReferences.ps1: zero findings.
• git diff --check: passed.
• A broader macOS startup/readiness selection had 37 passed and two failures (StartupWritesRecordsToTheSuppliedDiagnosticLog, UnavailableDiagnosticsWarnsOnceAndStillRunsTheCommand). Windows validation remains required; these are not reported as green or proven unrelated.
• Hosted Windows quality passed with zero warnings/errors; full Release suite: 1,298 passed, zero failed/skipped. Coverage rerun: 1,298 passed. scripts/Test-NativeAotCli.Tests.ps1: 29 native scenarios passed. Host validation job. The native JSON failure scenario now checks both setup and status errors retain capability and do not fabricate readiness/credentials. Both unsigned x64 and ARM64 package build jobs passed, and all required CI checks are green.
• Azure Crabbox acquisition attempted with provider azure, target windows, mode normal: HTTP 429 cost_limit_exceeded, fleet active lease limit 21/20. No lease ID or run URL allocated; no remote test executed.
• Required rubber-duck review: no actionable correctness/security findings. Review identified missing installed-package onboarding proof and original failing JSON as limitations. AutoReview not requested or run.

Real behavior proof

The strengthened regression drives the real Program.RunAsync exception boundary with fixture-owned diagnostics. It proves the error producer preserves the integration contract without reporting success. This is not installed-package or visible wizard proof.

Parallels platform and clean Store baseline proof: Only the disposable clone Windows 11 issue1672 proof was used. The original VM remains stopped and untouched.

• Before upgrade: Windows ARM64 26200.9457; actual pinned MXC SDK 0.8.0 probe returned isolationSessionAvailable=false.
• After supported Insider enrollment and Windows Update: Windows Pro Insider 26340.9616, version 26H2; the same SDK's actual signed-in-user wxc-exec.exe --probe returned exit 0, isolationSessionAvailable=true.
• Store Companion 2026.9.803.0 installed and launched through normal package activation with a fresh default profile. Store Gateway 2026.9.800.0 was installed by its wizard. Both packages: SignatureKind=Store, Status=Ok.
• Selected native onboarding. Device support, package acquisition, profile preparation/configuration validation, and Gateway startup/verification completed automatically. The wizard reached Connect your AI, with Connecting to your gateway: Complete. No manual clawctl setup was run.
• Subsequent package-qualified clawctl status --json: exit 0, ok=true, integration isolated-session version 1, session running, an iso: sandbox ID, Node 24.21.0, Gateway running.
• Package-qualified version proof: Store package build commit beacce88d7864972df9e5fa9f453d06626d833f5; payload OpenClaw 2026.9.8, commit fc23bc864e4553c2d215e479eeec47b67a0bf943.

This proves real MXC session setup and native Gateway execution in Parallels. It is an unpatched current-Store baseline, not proof of PR #164. The original issue used Companion 2026.9.520.0, Gateway 2026.9.701.0, Windows Enterprise 28120.3151, and retained Gateway/session state. The clean current-version run did not reproduce that failure.

Activation correction: The clone was unactivated when Insider 26340.9616 was offered, downloaded and installed. The earlier activation-blocker diagnosis was wrong for this clone. Enrollment used the maintainer's Insider account and Windows' supported UI. No fake enrollment, safeguard bypass, key change, purchase, or new account was used.

Current-head real lifecycle-contention comparison

Tested on the same Insider ARM64 clone with the same released Dev Companion 2026.9.803.4092, fresh separate tray profiles, actual pinned MXC SDK 0.8.0, Node 24.21.0, and OpenClaw payload commit fc23bc864e4553c2d215e479eeec47b67a0bf943.

Used actual CI NativeAOT binaries and the repository's canonical local-package layout helper to register separate Developer Mode identities. No fake backend, patched SDK, manual clawctl setup, Store package reset, or readiness/credential injection was used.

Build	Actual CI package input	Side-by-side identity	Real wizard result
Exact base bb3c7d1d4c8541649d9bd8e61cf1dbb0400ebfff	ARM64 0.1.836.1, SHA-256 ebc5b0b35a7430964a80a733f0b4f2438d4b6cba32184f1578bbe88c02a6e261	OpenClawFoundation.OpenClawGateway-issuebefore_rfcbke2p71se2	Profile preparation failed with the exact reported unsupported isolated-session contract error.
PR CI merge ad32d0092fa445903ff7990b53ee573b23ff446b	ARM64 0.1.837.1, SHA-256 28707acd36916f3468929979850c36e0d22f1adf1ab5a9cecccfd1ba682e8e36	OpenClawFoundation.OpenClawGateway-issueafter_rfcbke2p71se2	Profile preparation, isolated session configuration, and Gateway startup/verification completed automatically. Reached Connect your AI.

Verified merge parents are exact base bb3c7d1 and current PR head c7d42f7; layout node scripts/images/manifest are unchanged between them.

For each run, the proof controller held the real package-scoped Global\OpenClawSessionLifecycle_... mutex before selecting Set up gateway. It observed the actual qualified status --json process, held the mutex through its 30-second timeout, then released it three seconds after the process exited. Observed status lifetimes: base 30.124 seconds, PR 29.996 seconds. Base stopped at Prepare your Gateway profile with:

The installed Gateway MSIX does not expose Companion's isolated-session contract. Update the Gateway MSIX, then retry setup. Credentials were not sent.

The PR candidate proceeded without retry or manual setup after the same timeout. Actual UIAutomation diagnostics and focused Parallels screenshots captured the base error and current-head Connect your AI state.

After onboarding proof finished, repeated the real package-qualified producer call while holding each package's actual lifecycle mutex. Both returned exit 1, ok=false, command status, schema version 1, error type cli_error, and the same real timeout message. Neither fabricated session or credentials. The only capability difference was:

{
  "base": {"integration": null, "hasSession": false, "hasCredentials": false},
  "pr": {"integration": {"kind": "isolated-session", "version": 1}, "hasSession": false, "hasCredentials": false}
}

Error: another OpenClaw process is changing the session and did not finish within 30 seconds.

This is a controlled real reproduction of the reported UI symptom and proof that this PR fixes that operational-error case. It does not establish that lifecycle contention caused the original Spark incident, whose original failing JSON was not retained.

Not verified: original #1672 root cause and spontaneous reproduction on its exact OS/package/retained-state combination. This is outside the accepted bounded repair; keep the original incident open and unclaimed. The maintainer accepted the installed before/after evidence as satisfying this PR's reproduction gate.

[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 October 7, 2026, 9:41 PM ET / October 8, 2026, 01:41 UTC (Revision 9).

ClawSweeper review

What this changes

The branch preserves isolated-session capability metadata in clawctl operational error JSON and strengthens managed and NativeAOT regression coverage.

Example: Companion probes status while another process holds the session lifecycle lock

• Before: After the 30-second timeout, status returns an error without integration metadata and onboarding reports an unsupported isolated-session contract.
• After: The error retains isolated-session version 1, allowing existing automatic setup to continue after contention ends and reach Connect your AI.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The small repair is correct and proven through installed entry points, but it addresses only a demonstrated subset of the related onboarding report.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): Copied live output from real ARM64 NativeAOT packages exercises WriteFailure through the package-qualified status command and Companion onboarding under actual lifecycle contention: the base stops with an unsupported-contract error, while the verified current-head candidate completes automatic setup. Both status failures retain exit 1 and ok=false without session or credentials. This proves the bounded changed path, not the original incident’s cause; the additive response metadata changes no stored-data contract.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Partial
User problem: A supported Gateway can be reported as unsupported when its status probe encounters an operational exception, stopping automatic onboarding before setup.
Reason: The patch repairs an established package capability contract at its existing owner with minimal cost. It proves the operational-error case but does not establish a complete fix for the linked original Store incident.

Merge readiness

⛔ Blocked before merge - 2 items remain

This PR remains useful: current main omits capability metadata from operational exceptions, and real before/after evidence demonstrates the bounded repair. No actionable patch defect was found; the expressly reserved maintainer proof-sufficiency choice remains unresolved.

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

Decision needed

• Question: Does the exact-base/current-head installed lifecycle-contention comparison satisfy the recorded reproduction gate for this bounded repair, or must that gate include the original retained-state Store incident?
• Recommendation: Accept the bounded reproduction: Accept the installed before/after evidence for this producer repair while retaining Related wording and leaving the original incident investigation open.
• Why: The operational-error repair has sufficient real behavior proof, but the body expressly reserves whether that controlled scenario satisfies a stronger incident-specific gate; no recorded acceptance resolves that distinction.

Before merge

• Complete next step (P2) - Resolve whether the controlled installed before/after reproduction satisfies the expressly recorded incident-specific gate.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

None.

Agent review details

How this fits together

The Windows package’s clawctl command reports package capabilities and manages the isolated session used by OpenClaw. Companion consumes its JSON responses to detect support before invoking explicit setup and checking readiness.

flowchart TD
 A[Companion onboarding] --> B[Package-qualified status probe]
 B --> C[Session lifecycle operation]
 C --> D[Operational exception]
 D --> E[JSON error with package capability]
 E --> F[Existing explicit setup]
 F --> G[Success and readiness checks]
 G --> H[Continue onboarding]

Loading

Technical review

Best possible solution:

Keep capability reporting consistent at the existing error producer, preserve readiness and credential checks, and investigate the original Store incident separately.

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

Yes for the bounded producer defect: current-main source omits integration in operational failures, and the inspected real package transcript demonstrates the contention trigger. The original Store incident’s root cause remains unconfirmed.

Is this the best way to solve the issue?

Yes for the operational-error case: repairing the existing JSON producer preserves the established capability contract without adding provisioning logic or weakening readiness checks.

AGENTS.md: found and applied where relevant.

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

Provenance checked

• src/OpenClaw.Launcher/ClawCtlJson.cs: WriteFailure keeps the original intent (feat/clawctl json #69: Automation should consume a typed JSON contract, including command identity and stable failures; later isolated-session integration was established by the merged Companion integration work.)
• tests/OpenClaw.Launcher.Tests/ProgramStartupTests.cs keeps the original intent (feat/clawctl json #69: Failure documents preserve the selected command and provide stable machine-readable output.)
• tests/OpenClaw.Launcher.AotSmoke/SmokeProgram.cs keeps the original intent (feat/clawctl json #69: Native execution validates the versioned JSON failure contract through the production startup route.)
• docs/architecture.md: Companion integration keeps the original intent (fix: Companion cannot configure an isolated Gateway #134: Companion must configure the Gateway through the package-owned isolated session while preserving configuration and credential boundaries.)

Testing

Proof path: shipped entry point. Added test files: 2.

Security

None.

Evidence

What I checked:

• Introduced change and current-main defect: The pinned delta changes only the operational failure writer, two test files, and architecture documentation. Main’s WriteResult already attaches isolated-session version 1, but WriteFailure omits it; the branch adds the same existing metadata while preserving failure status, command, and error. (src/OpenClaw.Launcher/ClawCtlJson.cs:152, c7d42f727ec3)
• Production exception boundary: Program.RunAsync routes control-command exceptions through WriteFailure when JSON output is selected. The patch changes neither command dispatch nor session provisioning. (src/OpenClaw.Launcher/Program.cs:160, c7d42f727ec3)
• Consumer contract and independent safety checks: The PR’s onboarding claim affirmatively depends on Companion’s JSON consumer. DetectAsync rejects missing integration metadata; SetupAsync separately requires success and a ready session, and credential responses separately require success and valid configuration. Adding capability to an error does not satisfy those later checks. (src/OpenClaw.Connection/NativeGateway/NativeGatewayPackageClient.cs:55, 037c17dcb581)
• Real installed before/after evidence: The fully inspected PR body, captured sourceRevision fdf57c6d8cd6339c37627f46a77f9128f4fea4459ac4c1a67d5720fd40a596dc, reports ARM64 NativeAOT packages on Windows 26340.9616 with real MXC 0.8.0. Holding each package’s actual lifecycle mutex reproduced the unsupported-contract wizard error on exact base bb3c7d1; the verified test merge ad32d00 completed automatic onboarding under the same condition. Repeated package-qualified status calls returned exit 1 and ok=false for both builds; only the candidate retained integration, and neither emitted session or credential data. This is inspected copied live-output proof, not reviewer execution; the scratch directory contained no media files. (c7d42f727ec3)
• Exact test-merge identity: Raw commit records confirm test merge ad32d00 has exactly the pinned main parent bb3c7d1 followed by PR head c7d42f7, tying the reported candidate proof to this introduced change. (ad32d0092fa4)
• Regression and native coverage: Four managed cases assert error status, schema, selected command, and capability through Program.RunAsync. The native scenario now covers both setup and status errors and rejects fabricated session or Companion credential fields. The body reports these managed cases failed on unchanged production code. (tests/OpenClaw.Launcher.Tests/ProgramStartupTests.cs:148, c7d42f727ec3)

Likely related people:

• Paul Campbell (AgOS): Raw commit 9743772 adds src/OpenClaw.Launcher/ClawCtlJson.cs:126 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 9743772d6175; files: src/OpenClaw.Launcher/ClawCtlJson.cs)
• RomneyDa: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Review metrics

Metric	Value	Why it matters
Production and test growth	production +3 net lines; tests +16 net lines; documentation +5 net lines	The small production addition repairs the existing owner, with proportionate behavioral coverage rather than a competing implementation.

Labels

Label changes:

No label changes.

Label justifications:

• P2: This bounded error-contract repair addresses a demonstrated contention case without establishing an urgent current-release incident.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rank-up moves

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

• Resolve the expressly reserved incident-specific proof-sufficiency choice while preserving Related wording and the distinction from the original Store failure.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only; repair and merge need explicit maintainer commands such as @clawsweeper autofix or @clawsweeper automerge.

History

Review history (8 earlier review cycles)

• reviewed 2026-10-07T21:56:59.845Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-07T22:01:15.167Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-07T22:08:28.039Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-07T22:27:52.167Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-07T23:17:59.039Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-07T23:30:55.267Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-08T00:46:20.307Z sha c7d42f7 :: needs changes before merge. :: none
• reviewed 2026-10-08T01:16:34.388Z sha c7d42f7 :: blocked before merge. :: none

[RomneyDa]

Addressed the review's owner decision. The maintainer explicitly accepted: "Accept bounded reproduction; keep original incident open."

The accepted scope is the demonstrated operational-error contract defect: exact-base real lifecycle contention produces the reported unsupported-contract wizard error; the unchanged current PR head retains capability metadata and completes automatic onboarding under the same condition. This does not establish the original Spark incident's trigger or claim complete resolution of #1672. The issue remains open and Related, not Fixes.

Updated the PR body to record that decision. The reviewed head remains c7d42f727ec393c43652bde8d03564102fee2daa; no source changes were needed because the review found no actionable code defects. Required CI is green and GitHub reports mergeable. No merge is authorized.

@clawsweeper re-review

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The item is closed; no stale verdict was published.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/37715185435
• Updated: 2026-10-08T01:54:07.491Z