Repository navigation
feat: explain native stage mismatches with clawctl status --native - #264
paulcam206 wants to merge 1 commit into
Conversation
|
🦞👀 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. |
|
Codex review: needs maintainer review before merge. What this changesAdds optional native-dependency inspection to clawctl status, with human and JSON reports. Example: The installed fs-safe package is 0.26.5, but its staged architecture package remains at 0.25.0.
Review scores
ProductKind: Feature · Worth it: Yes · Fix scope: Complete Merge readiness✅ Ready for maintainer review Keep open: this collaborator-authored feature is absent from main, and the previous reporting defect is fixed; no new blocking defect was found. Priority: P2 Before mergeNone. FindingsNone. Agent review detailsHow this fits togetherThe launcher sends an inspection request to the existing isolated-session helper, which compares installed inventory with the recorded native stage and returns facts for status rendering. flowchart LR
A[clawctl status native] --> B[Launcher]
B --> C[Session protocol]
C --> D[Agent inspector]
E[Installed inventory] --> D
F[Recorded native stage] --> D
D --> G[Human and JSON output]
Technical reviewBest possible solution: Retain this focused diagnostic extension on the shared verifier and land it after its admission-and-repair dependency. Do we have a high-confidence way to reproduce the issue? The reporting need is supported by the linked incident and supplied installed-upgrade output; this review inspected source and evidence without running target code. Is this the best way to solve the issue? The change extends the existing command tree, session executor, protocol, verifier, and renderers while keeping repair under setup. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning medium; reviewed against c6ef88e098ae. Provenance checked
TestingProof path: shipped entry point. SecurityNone. EvidenceWhat I checked:
Likely related people:
Preflight sourceSource unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified. LabelsLabel changes:
Label justifications:
Rating scale6/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. WorkflowClawSweeper edits this one comment on every review. Comment HistoryReview history (1 earlier review cycle)
Reviewed November 16, 2026, 10:54 PM ET / November 17, 2026, 03:54 UTC (Revision 2). |
When a launch reports native-stage-stale, or a native helper fails inside the session, there was no way to see how the agent's staged native copies compared with the installed package without opening an agent shell and probing by hand. clawctl status --native asks the session helper, under the agent identity, to run the same inventory and verification launch admission uses and report the state, file counts, content identifiers, and for each native-bearing package its source and staged versions and digests and whether it resolves from the stage or the immutable package. It never stages, repairs, loads native code, or reports paths; when no fresh inspection is possible it says why instead of claiming a state. A mismatch exits 1 and names clawctl setup. Plain status is unchanged. Related: #222
9a6f928 to
b04a39d
Compare
|
@clawsweeper re-review |
|
🦞👀 Re-review progress:
|
Related: #222
What Problem This Solves
Fixes: when a launch refused a stale or damaged native dependency stage, nothing showed which packages differed, whether a package resolved from the stage or the immutable package, or what setup would change. That left #222-style mismatches hard to diagnose from logs alone. Affects
clawctl status.User Impact
User impact:
clawctl status --native(and--native --json) reports whether the agent's staged native dependencies match the installed package. The report gives file counts, content IDs and, for each package, source and staged versions, short digests, and whether the package resolves from the stage or the immutable package. A mismatch exits nonzero withclawctl setupas the repair. Plainclawctl statusis unchanged and does not inspect the stage.Why This Change Was Made
This is the second of two stacked PRs. It builds on #262, which refuses a mismatched stage before Node.js starts, and has
clawctl setuppublish a new verified generation without disturbing held stages.The opt-in inspection runs read-only under the agent identity, using the same inventory and verification as admission. It reports no paths, stages nothing, loads no native code, and never walks a link the verifier rejected. A rejected layout, or a recorded stage it cannot lease, reports
resolvesFrom: unknownrather than guessing. The helper request and report are a narrow versioned contract with source-generated JSON, bounded to 64 packages.Evidence
Head b04a39d on #262's head 7413c50 (base
origin/mainc6ef88e). The installed proof ran at this head and covers both PRs.Installed upgrade on an isolated Windows guest (packages built at b04a39d)
Environment: one disposable Hyper-V guest (Windows build 29683 x64, 4 vCPU / 8 GiB) from a clean template plus the official VC++ 14.52 x64 redistributable, which is a prerequisite here, not under test. Packages: two MSIXes built by
scripts\Build-LocalMSIX.ps1from a clean tree at b04a39d (sourceTreeDirty: false) with the published payloads, test-signed in the guest only, and installed withAdd-AppxPackageas an in-place update. A′ is 0.1.10000.21 with payload v2026.10.6 (fe06181d, fs-safe 0.25.0, where only the architecture package is native-bearing). B′ is 0.1.10000.22 with payload v2026.11.1 (4ffdd204, fs-safe 0.26.5, where@openclaw/fs-safegains a helper.exe). Both use Node.js 24.22.1. Every package command ran in the interactive session; results are recorded as exit codes and JSON.Upgrade, A′ then B′:
clawctl setup,companion prepare, andgateway-service startsucceeded, recording stage generation35decda5….gateway-service startadopted the running Gateway (disposition: adopted, the same attempt as before).openclaw --version,clawctl pwsh --command …, andclawctl backup --jsonall exited 1 before starting anything. Text output saidstaged from different package content (expected 8f55ca68…, found d3511a8e…) [stale-source; 209 of 931 files verified, 697 missing, 28 unexpected, 25 changed] … Run 'clawctl setup' to refresh them., andbackup --jsonreturnederror.type: "native_stage_stale".setup.jsonwas unchanged by the refusals.clawctl status --native --jsonreportedstate: stale-source,provenance: package-inventory,repair: clawctl setup. It showed the OpenClaw 2026.10.6 — Gateway exit code 78; SQLite migration blocked by fs-safe helper-unavailable #222 split:@openclaw/fs-safe0.26.5resolvesFrom: immutable(no staged copy), while@openclaw/fs-safe-win32-x64-msvcwas staged at 0.25.0 against source 0.26.5.clawctl setup(17 s) kept the same sandbox ID and published generation7037cd44…. The running Gateway, the same listener process before and after, kept35decda5…; both generations were present after repair.status --nativereportedcurrent, 931/931 verified, with both fs-safe packages staged at 0.26.5.parentNative: true,isolatedWorker: true). Under A′ the same probe reported the worker ashelper-unavailable.clawctl backup --jsonsucceeded with a verified archive.gateway-service restart, the nextclawctl setupreclaimed35decda5….Damage behind a retained marker, with a shell held open:
clawctl pwshsession stayed running on generation7037cd44…. The fs-safe worker script was then deleted from that stage, leaving its marker in place.openclaw --versionexited 1 with[incomplete; 930 of 931 files verified, 1 missing, 0 unexpected, 0 changed].status --nativereportedincomplete, with@openclaw/fs-saferesolvingmixed.gateway-service restart --jsonreturnederror.type: "native_stage_stale".clawctl setup(10 s) kept the same sandbox and publishedefa71e0b…. The held shell was still running and both generations were present.parentNative: trueandisolatedWorker: true, andgateway-service startsucceeded. The released shell exited 0.clawctl setupstill succeeded and left that generation whole. After the marker was made writable, the next setup reclaimed it.User state: the same sandbox ID before the update, after each repair, and at the end. Hashes of the agent's
openclaw.jsonand three synthetic markers with distinct random contents (DB, config, jobs) were identical before and after each repair.Cleanup:
clawctl teardown --forceand package removal left 0 packages, agent accounts, profiles, and scheduled tasks; the guest was then destroyed.Observed and unrelated to this change: when two
clawctl pwshinvocations share one console, the second exits only after the first ends, although its command has already completed. The host's console-input relay (MxcSdkSessionClient) is unchanged here. Separate consoles complete independently.Local lanes
.\scripts\Test-DotNetQuality.ps1: passed at 7413c50 and b04a39d.dotnet test .\OpenClaw.Gateway.MSIX.slnx --configuration Release: 1711/1711 at 7413c50, 1716/1716 at b04a39d..\scripts\Test-NativeAotCli.Tests.ps1: passed at both heads. At b04a39d it also round-trips--inspect-nativeand thestatusnativeStageJSON under NativeAOT..\scripts\Test-SessionNativeStagerEfs.Tests.ps1 -ApplicationDirectory <EFS-encrypted fixture>\app: passed at both heads..\scripts\Test-DocReferences.ps1: 0 findings.git -c core.whitespace= diff --check: clean.Tests added here:
NativeStageUpgradeScenarioTests:status --native --jsonreportsstale-source, with@openclaw/fs-saferesolving fromimmutableand no agent paths;statusdoes not inspect;currentafter repair.SessionNativeStageInspectorTests:unsupported-layoutwithresolvesFrom: unknown, without being walked;missingwithresolvesFrom: unknown. This test was mutation-checked: it fails if resolution is inferred from skipped reads.ClawCtlConsoleTests: human rendering.--inspect-nativeand thestatusJSON.Not run: ARM64 lanes and an ARM64 installed upgrade.