improve: diagnostics bundles explain failed commands and name the build they ran on - #120
Conversation
A field bundle recorded only "Unhandled failure: MxcException": setup had provisioned a session and MXC refused to start it, but the host log dropped the backend's error and the bundle named neither the build nor how it was installed. - Log every failure through one describer: type, message, MXC code, backend code and failing operation, Win32 error or HRESULT, and every inner cause. The last-chance handler also records stack traces. - Carry the MXC error envelope's operation on MxcException, and keep exit code, diagnostics, and a bounded output excerpt when no envelope parses. - Log failures that previously reached only the console: status probes, gateway inspection and stop, readiness probes, recovery registration, JSON setup, and open. Keep the guest's own error on a failed inspection. - Preserve inner exceptions at result-read and protocol JSON wraps, and log how each attached run ended. - Record an Environment line at every host start and in the collect-logs manifest: Windows build and UBR, architectures, package full name with origin (Developer Mode loose layout, Store-signed, developer-signed MSIX) and install path, package and payload versions, MXC runtime and wire schema, Node.js, and .NET. Log the support decision's evidence too. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
collect-logs narrated a single opening status while it started the isolated session and collected guest files. It now reports each source as it gathers it: the session start, the OpenClaw logs and configuration collected inside it, each host record read into the bundle, and the staged agent files. The progress flows through the shared NarrateOperationAsync path, so narration stays on standard error, redirected standard error keeps a line per source, and --json narrates nothing. The handler now takes host paths from the session runtime, as its sibling handlers do, so the narrated path is covered end to end. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…tcome A field bundle for a gateway that failed twice held neither launch's own output nor supervisor status, although the failure message tells users that collect-logs captures the gateway log. The host log also recorded only that each start began, never how it ended. - Collect each gateway launch's log and supervisor status from the shared workspace, including earlier launches the gateway record no longer names. Files must carry the recorded session generation, reparse points are refused, only the newest 10 launches are kept, and each file is cut to its last 1 MiB. Reading them needs no running session. - Log every gateway start's outcome, covering gateway-service start and restart and the automatic start after openclaw. - Redact URL query or fragment credentials, environment-style assignments, and HTTP authorization header credentials. Run every redaction pattern non-backtracking, so crafted guest text cannot stall collection. - Keep guest-written text on its own host-log line. - Point the troubleshooting guide at the collected launch logs instead of a status log tail that is no longer printed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
5aa83b9 to
8b80863
Compare
|
Codex review: needs maintainer review before merge. Reviewed September 24, 2026, 6:30 PM ET / 22:30 UTC (Revision 2). ClawSweeper reviewWhat this changesThe branch adds build and failure details to Windows host diagnostics, includes bounded gateway launch files in collected ZIPs, and narrates collection progress. Merge readiness✅ Ready for maintainer review Keep open. Current main still lacks the requested diagnostic evidence. The latest head addresses the previous manifest-redaction finding, and an exact-head Windows run supports the repair. Priority: P2 Review scores
Verification
How this fits togetherThe Windows launcher manages the isolated session and gateway, and records host diagnostics. flowchart LR
A[clawctl commands] --> B[Windows launcher]
B --> C[Isolated session and gateway]
B --> D[Host diagnostics]
C --> E[Agent and gateway files]
D --> F[Bundle collector]
E --> F
F --> G[Redacted ZIP and notes]
Before mergeNone. Agent review detailsSecurityNone. Review metrics
Technical reviewBest possible solution: Keep diagnostics in the existing launcher and bundle owners, with bounded gateway history, useful failure context, and redaction before ZIP or note output. Do we have a high-confidence way to reproduce the issue? Yes. On current main, a failed gateway start followed by Is this the best way to solve the issue? Yes. The branch extends the existing diagnostic bundle owner and uses the existing command narration path; the exact-head Windows run demonstrates the intended collected output. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against b06135e97580. LabelsLabel changes:
Label justifications:
EvidenceWhat I checked:
Likely related people:
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
HistoryReview history (1 earlier review cycle)
|
A failure note quotes the failure's full detail, which for a malformed MXC response includes the executor's raw output and diagnostics. The notes were written to manifest.txt and returned for console and JSON output without the redaction applied to collected file text, so a credential-shaped value in executor output could leave the machine in a shared bundle. Every note, and the manifest's environment line, now passes through DiagnosticsRedactor before it is written or returned. A bundle test drives malformed executor output carrying a bearer token and an API key assignment through the real MXC client and asserts neither reaches the manifest or the returned notes, while the failure detail itself survives. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
🦞👀 Pull request received. I will update this pull request when review starts. ClawSweeper review completeClawSweeper finished reviewing this revision. The review result is being finalized. |
|
ClawSweeper status: review started. I am starting a fresh review of this pull request: improve: diagnostics bundles explain failed commands and name the build they ran on This is item 1/1 in the current shard. Shard 0/1. This temporary status tracks the active review worker. The completed review will appear in the durable ClawSweeper review comment. Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted. |
What Problem This Solves
Fixes:
clawctl collect-logsbundles can't explain a failed setup, command, or gateway start. Theopenclaw.exelauncher's diagnostic log recorded only an exception type and never named the Windows build, the package version, or how the package was installed. Bundles also left out the gateway's own output, although a failed gateway start tells users to runclawctl collect-logsto capture it.User Impact
User impact: a
clawctl collect-logsbundle now shows why a command or gateway start failed and what it ran on, so a report can be diagnosed without follow-up questions. The command also names each source as it gathers it.Diagnostic log and bundle: every host start records the Windows build and update revision, and how the package was installed:
It also records the package, OpenClaw payload, MXC, Node.js, and .NET versions. Failures record their message, MXC error and failing operation, Windows error code, and inner causes. Every gateway start records its outcome and the message the user saw.
Gateway launch logs:
gateway/in the ZIP holds each gateway launch's own output and supervisor status, including earlier launches that a later start replaced. Only the newest 10 launches are kept, and each file is cut to its last 1 MiB.Narration:
collect-logsnarrates each source on standard error.--jsonoutput is unchanged and narrates nothing.Console output (failure paths only):
collect-logsnotes about files it couldn't collect now include the underlying cause.The guest reported: <reason>.Risk: bundles now carry full failure messages, gateway output, and the install path. For a local loose-layout deployment, that path is the developer's checkout. Redaction now also covers:
#token=;The bundle's "review before sharing" guidance still applies. Redaction applies to every collected file, to
manifest.txt, and to the notescollect-logsprints, because a note can quote a failure's raw detail. Browser-launch failures still log only a Windows error code, because the message would contain the Control UI URL and its token.Why This Change Was Made
A field bundle from a failed
clawctl setupcontained onlyUnhandled failure: MxcException. MXC had provisioned the isolated session and then refused to start it, but the backend's error, code, and failing operation were dropped. Several other failures reached only the console: status probes, gateway inspection and stop, readiness probes, and logon-task registration.A second field bundle came from a gateway that failed twice with
another OpenClaw process owns gateway-lifecycle, because an embedded TUI from onboarding was still running. That bundle had neither launch's output or supervisor status, and the first failure came from a launch the gateway record no longer named. Its host log showed each start beginning but never how it ended.One failure formatter now owns what the log records. Each host start writes one
Environment:line, and every bundle's manifest repeats it. The gateway controller logs each start's outcome in the one method every start path goes through. #109 added timing records that intentionally log only exception types. The failure records added here are separate, anddocs/architecture.mddescribes both.Implementation notes
DiagnosticFailureformats a failure as its type and message, then MXC code, backend code, and operation, then Win32 error or HRESULT, then every inner cause. Aggregated causes are numbered. The last-chance handler also records stack traces.MxcExceptioncarries the error envelope'soperation. When the executor produces no parsable envelope, the error keeps its exit code, its diagnostics, and up to 512 characters of its output.openclawandclawctl pwshruns log their exit code, so a missing exit line shows that the host was killed.HostEnvironmentreads the package origin throughGetStagedPackageOrigin(exported bykernelbase.dll) and development mode throughGetCurrentPackageInfo. Any fact it can't read is described as unavailable, so the environment line never fails a command.collect-logsprogress uses fix: clawctl commands show nothing until long operations finish #108'sNarrateOperationAsync, and the handler takes host paths from the session runtime, as its sibling handlers do.SessionWorkspaceOperation/TrustedPath, so a session that can no longer start still yields them. Onlygateway-<recorded generation>-*.logand.status.jsonare taken. Reparse points are refused, launches are grouped and the newest 10 kept, and each read is bounded to its last 1 MiB and cut at a line boundary.DiagnosticsRedactorpattern now runs withRegexOptions.NonBacktracking. The redacted text is largely guest-written, and the backtracking engine took quadratic time on crafted input; one 360 KB line exceeded a 5 s cap, compared with 16 ms now. A NativeAOT scenario runs the redactor.DiagnosticFailure.SingleLine, so a line break or escape sequence cannot forge a host-log entry.gateway-service statusno longer prints a gateway log tail. The code that did,GatewayControlOutput, has had no production caller since Improve clawctl output readability and color #66. The troubleshooting guide now points to the collected launch logs instead; removing or rewiring that class is left for a follow-up.Evidence
Head:
ec45dcb9ef737889cba3097e62d6891cb0474b9a, rebased onto main6191262. The automated lanes and the real run below come from this head on the author's Windows machine. The origin-mapping probe is a read-only OS check that doesn't depend on any code.Automated lanes (at
ec45dcb).\scripts\Test-DotNetQuality.ps1: passed with 0 warnings and 0 errors.dotnet test .\OpenClaw.Gateway.MSIX.slnx --configuration Release --no-restore: 1202 passed, 0 failed. This includes:collect-logshandler: the per-source narration appears in order on standard error and the result on standard output, and--jsonproduces one parsable document with empty standard error;gateway/with their supervisor status. The Control UI#token=in the later log is redacted. A request file and another generation's log are left out;OPENAI_API_KEY=assignment through the real MXC client. Neither credential reachesmanifest.txtor the returned notes, while the failure detail does;.\scripts\Test-NativeAotCli.Tests.ps1: 29 scenarios passed under theclawctlalias, including package-provenance binding and redaction under NativeAOT. The rerun under a wrong executable name fails only the alias check, as designed..\scripts\Test-DocReferences.ps1: 0 findings.git diff --check: clean.Review findings addressed
8b80863found that bundle notes quoting raw MXC executor output reachedmanifest.txtand the command's output without redaction.ec45dcbredacts every note and the manifest's environment line, and adds the regression test above.Real run (at
ec45dcb)Environment:
Deploy-LocalPackage.ps1 -Patch diag-ec45dcb -Architecture x64, which also ranclawctl setup.ec9c1a13).clawctl-diag-ec45dcb --versionreported commitec45dcb9ef737889cba3097e62d6891cb0474b9a.Gateway starts, in order:
gateway-service startexited 1 withexited during startup … The supervisor reported: the application exited with code 78.gateway.mode localand a free port (59363) were set throughclawctl-diag-ec45dcb pwsh --command, the next start failed withThe gateway's state could not be established, so a new one was not started: Access is denied.gateway-service statusthen reported the earlier launch asstoppedwith exit code 78.collect-logs --no-colorwith the two streams redirected to separate files exited 0 in 550 ms. Standard error (narration):Standard output contained only the result:
Included: host and session diagnostics, the review guidance, and the bundle path on its own line.collect-logs --jsonexited 0 in 486 ms, with 0 bytes on standard error and one document containing"ok": true,"included": "host-and-session", and"notes": [].The bundle held 13 entries, including two launches under
gateway/, newest first:The earlier failed launch is collected even though the gateway record now names the later one. The bundled host log records each start's outcome and the transient inspection failure:
manifest.txt, read inside the packaged process:Supported from BackendProbe evidence; host build 26693.1000; … backend probe isolation sessions available, tier base-container, warnings none) and the pwsh exit (PowerShell 7 exited with code 0.).clawctl-diag-ec45dcb teardown --forceremoved the session, andDeploy-LocalPackage.ps1 -Unregister -Patch diag-ec45dcbunregistered the patch.Origin mapping
A read-only
GetStagedPackageOriginprobe of the machine's installed packages matchedGet-AppxPackage(2026-09-23):This product's own Store install,
OpenClawFoundation.OpenClawGateway_2026.9.404.0_x64__rfcbke2p71se2, reports originStore(2026-09-24).Local ClawSweeper range review at
ec45dcbagainst main6191262: the patch was reviewed as correct (confidence 0.86), security cleared, and real behavior proof sufficient, with no findings.Not run