Doctor: convert read-only health checks by giodl73-repo · Pull Request #83198 · openclaw/openclaw

giodl73-repo · 2026-05-17T17:02:56Z

Summary

This is the first focused follow-up to #80055. It keeps the conversion deliberately low-risk by moving read-only doctor checks into health-check detect() findings while preserving legacy doctor --fix behavior until each repair area has a real modern repair() owner.

This PR adds:

a checked conversion plan that maps existing doctor contributions to their target health checks;
health-check target metadata on doctor contributions;
read-only findings for security, browser readiness, workspace suggestions, legacy WhatsApp crontab warnings, and gateway platform notes. Session snapshots stay on the legacy doctor run path in this slice until they have a structured detector.

Behavior addressed

Doctor follow-up conversions are easier to review when each area moves from run(ctx) to detect() independently. This PR converts read-only checks first, so doctor --lint can report these findings through structured health output without changing repair behavior.

Migration rule

This PR treats the first slice as a reporting conversion, not a repair takeover.

doctor --lint uses the new detect() findings for converted checks. doctor --fix keeps the existing legacy run() / maybeRepair*() behavior unless a specific check has a complete modern repair() implementation. Placeholder health checks are inventory targets only; they do not suppress legacy notes or repairs yet. Checks that do not yet have a structured detector are deliberately left off the lint registry to avoid false-clean results.

That means later area-specific PRs can safely move one check at a time: first add structured detection, then add scoped repair, then remove or skip the legacy path only when the modern path fully owns the behavior.

Staging note

This PR is stacked on current main after #80055 landed. The full conversion branch is intentionally not included here; future follow-ups should be opened area by area after this first read-only slice.

Real behavior proof

Fresh deterministic proof artifacts:

Behavior addressed: This PR converts read-only doctor checks to structured health detect() findings so doctor --lint can report them without repair-mode execution.

Real environment tested: WSL Ubuntu source checkout, branch doctor-detection-conversion-plan, based on upstream/main after #80055.

Exact steps or command run after this patch:

tmp=$(mktemp -d)
OPENCLAW_HOME="$tmp/.openclaw" pnpm openclaw doctor --lint --only core/doctor/workspace-suggestions

Evidence after fix: The real OpenClaw CLI ran one converted read-only doctor check and emitted a structured lint finding without entering repair mode.

$ node scripts/run-node.mjs doctor --lint --only core/doctor/workspace-suggestions
{"ok":false,"checksRun":1,"checksSkipped":44,"findings":[{"checkId":"core/doctor/workspace-suggestions","severity":"info","message":"Memory system not found in workspace.","fixHint":"Paste this into your agent:\n\nInstall the memory system by applying:\nhttps://github.com/openclaw/openclaw/commit/9ffea23f31ca1df5183b25668f8f814bee0fb34e\nhttps://github.com/openclaw/openclaw/commit/7d1fee70e76f2f634f1b41fca927ee663914183a"}]}
[ELIFECYCLE] Command failed with exit code 1.

Observed result after fix: doctor --lint executed the selected converted check in read-only mode, reported core/doctor/workspace-suggestions as a structured finding, skipped the other 44 checks because of --only, and returned the expected lint-failure exit when a finding was present.

Supplemental verification:

node scripts/run-vitest.mjs src/flows/doctor-health-conversion-plan.test.ts src/flows/doctor-core-checks.test.ts src/commands/doctor-lint.test.ts src/commands/doctor-cron.test.ts src/commands/doctor-platform-notes.launchctl-env-overrides.test.ts src/flows/doctor-repair-flow.test.ts
node_modules/.bin/tsgo -p tsconfig.core.json --noEmit --incremental false --pretty false
git diff --check

Supplemental result: Focused Vitest proof passed: 6 files, 43 tests. Core typecheck passed. git diff --check passed with no whitespace/conflict-marker findings.

What was not tested: Full repository CI and broad Crabbox/Testbox validation were not run locally for this draft; this branch is intended as a narrow follow-up behind #80055.

clawsweeper · 2026-05-17T17:05:04Z

Codex review: needs maintainer review before merge.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

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.

Summary
This PR converts several read-only doctor notes into structured doctor --lint health-check detections and adds a doctor health conversion plan.

Reproducibility: not applicable. as a feature PR rather than a bug report. The changed behavior is demonstrated by linked live CLI output and by source inspection of the PR head.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Current head looks normally mergeable after the false-clean fix, with sufficient live proof for the core behavior and remaining confidence tied to CI plus maintainer acceptance of lint compatibility risk.

Rank-up moves:

Let current head checks finish cleanly.
Maintainer should accept or narrow the expanded default doctor --lint coverage before merge.

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

PR egg
✨ Hatched: 🥚 common Neon Lint Imp

        .--^^^^--.           
     .-'  o    o  '-.        
    /       \__/      \      
   |    /\  ____  /\   |     
   |   /  \/____\/  \  |     
    \  \_.------._/  /       
     '._  `----'  _.'        
        '-.____.-'           
       _/|_|  |_|\_          
      /__|      |__\         
       .-----------.         
      '-------------'

Rarity: 🥚 common.
Trait: collects tiny proofs.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Neon Lint Imp in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
How to hatch it: reach status: 👀 ready for maintainer look or status: 🚀 automerge armed; that usually means sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

Real behavior proof
Sufficient (live_output): The PR body links live CLI output showing doctor --lint --only core/doctor/workspace-suggestions emitting a structured after-fix finding from a real OpenClaw run.

Risk before merge
Why this matters: - Merging expands default doctor --lint coverage, so existing operator automation may start failing on newly structured info/warning findings that legacy doctor previously only printed.

The current head still had GitHub checks in progress and mergeable_state: unstable at inspection time.
The PR body proof demonstrates one converted check; broader confidence comes from source inspection, targeted tests, and CI rather than a full Crabbox/Testbox run.

Maintainer options:

Accept expanded lint after CI
Merge once current checks finish if maintainers intentionally want the newly converted read-only findings to participate in default doctor --lint exit behavior.
Narrow the default lint surface
If existing lint gates should not fail on workspace suggestions or other advisory checks by default, defer those checks or require explicit selection before merge.

Next step before merge
No narrow automated repair remains; the next action is maintainer acceptance of the expanded lint gate plus normal current-head CI review.

Security
Cleared: No concrete security or supply-chain regression found; the diff refactors existing doctor diagnostics into read-only collectors and lint checks without new dependencies or secret writes.

Review details

Best possible solution:

Land only after maintainers accept the expanded lint semantics and current head checks finish cleanly, while keeping planned-only conversion targets out of the runtime registry until real detectors exist.

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

Not applicable as a feature PR rather than a bug report. The changed behavior is demonstrated by linked live CLI output and by source inspection of the PR head.

Is this the best way to solve the issue?

Yes, with maintainer acceptance of the lint-surface expansion. The latest head uses real detectors for registered checks, leaves planned-only work in the conversion inventory, and adds coverage for unknown --only targets.

Label justifications:

P2: This is a normal-priority doctor CLI health-check migration with limited but real operator and automation impact.
merge-risk: 🚨 compatibility: Existing users running default doctor --lint can see new findings and nonzero exits after upgrade.
merge-risk: 🚨 automation: Automation that treats doctor --lint as a gate may change behavior because the PR expands the registered lint check set.

What I checked:

PR head removes runtime no-op placeholders: convertedWorkflowChecks now contains implemented detector objects directly instead of the prior createConvertedWorkflowCheck() placeholder list, so unimplemented targets are no longer registered as clean lint checks. (src/flows/doctor-core-checks.ts:712, 1c8558a7e425)
Unknown targeted lint IDs now fail closed: runDoctorLintChecks() builds the registered ID set and emits an error finding for any --only ID not present in the active health registry. (src/flows/doctor-lint-flow.ts:31, 1c8558a7e425)
Deferred session snapshot target remains off lint registry: The conversion plan maps session snapshots to doctor-run/session-snapshots and explicitly says not to register a clean core lint target until a structured detector exists. (src/flows/doctor-health-conversion-plan.ts:109, 1c8558a7e425)
Regression coverage targets the prior false-clean issue: PR head adds tests proving representative planned-only targets are not registered and unknown --only selections return an error finding instead of a clean run. (src/flows/doctor-core-checks.test.ts:60, 1c8558a7e425)
Current main lint contract: Current main registers core health checks, reads the config snapshot with { observe: false }, and runs selected health checks through the lint runner, which is the behavior this PR extends. (src/commands/doctor-lint.ts:38, 1fb09069c342)
Prior review context and follow-up commits: The durable ClawSweeper review at commit 3c331106722b identified no-op placeholders as the blocker; the comparison to current head shows follow-up commits e24823ce and 1c8558a7 removing placeholders and adding registry/selection tests. (1c8558a7e425)

Likely related people:

giodl73-repo: Authored the merged doctor health-check contract and doctor --lint implementation in the related merged PR, and this PR is the focused follow-up on the same migration path. (role: feature-history owner; confidence: high; commits: 9a5f2f61e76f, c8b8af2ad179, 1c8558a7e425; files: src/commands/doctor-lint.ts, src/flows/doctor-core-checks.ts, src/flows/doctor-lint-flow.ts)
Peter Steinberger: Recent history shows major doctor orchestration and module-splitting work around the contribution flow that this PR extends. (role: doctor flow refactor owner; confidence: medium; commits: 7d6d642cb825, 2ca936ee9869; files: src/flows/doctor-health-contributions.ts, src/commands/doctor-security.ts)
Vincent Koc: Recent current-main history includes doctor CLI health-check work adjacent to one of the converted read-only checks. (role: adjacent doctor health contributor; confidence: low; commits: 8143b9a23ead; files: src/flows/doctor-health-contributions.ts, src/commands/doctor-claude-cli.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 1fb09069c342.

giodl73-repo · 2026-05-18T02:58:39Z

Addressed the two P1s from ClawSweeper:

Restored the health repair preview contract: dryRun, diff, diffs, and effects are back in the runner and SDK exports. Dry-run repairs no longer apply returned config or run post-repair validation.
Restored default doctor --lint coverage and made final config validation use readConfigFileSnapshot({ observe: false }) so the default lint path remains read-only.

Verification:

node scripts/run-vitest.mjs src/flows/doctor-health-conversion-plan.test.ts src/flows/doctor-core-checks.test.ts src/commands/doctor-lint.test.ts src/flows/doctor-repair-flow.test.ts hit local Windows spawn EPERM before Vitest started.
node node_modules/vitest/vitest.mjs run src/flows/doctor-health-conversion-plan.test.ts src/flows/doctor-core-checks.test.ts src/commands/doctor-lint.test.ts src/flows/doctor-repair-flow.test.ts --reporter verbose passed: 4 files, 19 tests.
git diff --check passed.
node_modules\.bin\tsgo.cmd -p tsconfig.core.json --noEmit --incremental false --pretty false, pnpm exec tsgo ..., and WSL ./node_modules/.bin/tsgo ... are blocked in this checkout by local executable/package issues (Access is denied on Windows; missing Linux native package in WSL).
wsl bash -lc 'cd /mnt/c/src/openclaw-core && codex review --uncommitted' found no discrete correctness issues in the fix.
wsl bash -lc 'cd /mnt/c/src/openclaw-core && codex review --base origin/main' found no discrete actionable regressions on the updated branch.

@clawsweeper re-review

clawsweeper · 2026-05-18T03:00:11Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26011153325
Updated: 2026-05-18T03:07:29.504Z

giodl73-repo · 2026-05-18T14:50:17Z

Updated 83198 against latest origin/main and resolved the merge conflicts.

What changed in this refresh:

Rebuilt the branch on top of current main as the remaining read-only doctor conversion commits, instead of replaying the already-merged doctor lint base.
Kept the newer core/doctor/browser-clawd-profile-residue health check from main alongside the converted read-only checks.
Kept the ClawSweeper P1 fixes from the previous update: repair preview contract (dryRun, diff, diffs, effects) is preserved, and final config validation uses readConfigFileSnapshot({ observe: false }) for lint.

Verification:

git diff --check passed.
node scripts/run-vitest.mjs src/flows/doctor-health-conversion-plan.test.ts src/flows/doctor-core-checks.test.ts src/commands/doctor-lint.test.ts src/flows/doctor-repair-flow.test.ts is still blocked locally by Windows spawn EPERM before Vitest starts.
Direct Vitest in the temporary clean worktree timed out; I killed the lingering node process before continuing.
node scripts/run-tsgo.mjs -p tsconfig.core.json --noEmit --incremental false --pretty false is still blocked locally by Access is denied in this Windows checkout.
WSL codex review --base origin/main in the temporary clean worktree hung until timeout, so CI/ClawSweeper is the next authoritative proof path for this pushed rebased branch.

@clawsweeper re-review

clawsweeper · 2026-05-18T14:52:13Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26041182246
Updated: 2026-05-18T14:59:46.383Z

* feat(doctor): convert read-only health checks * fix(doctor): keep read-only conversion gates green * fix(doctor): preserve health repair preview contract * fix(doctor): defer session snapshot lint target * fix(doctor): avoid false-clean lint placeholders * test(doctor): type conversion target registry check

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime cli CLI command changes scripts Repository scripts commands Command implementations size: XL maintainer Maintainer-authored PR labels May 17, 2026

giodl73-repo force-pushed the doctor-detection-conversion-plan branch from 38830c2 to 7c68a14 Compare May 17, 2026 17:03

giodl73-repo changed the title ~~Doctor: convert remaining health checks~~ Doctor: convert read-only health checks May 17, 2026

giodl73-repo force-pushed the doctor-detection-conversion-plan branch from 7c68a14 to a1003da Compare May 17, 2026 17:11

openclaw-barnacle Bot added the extensions: qa-lab label May 17, 2026

openclaw-barnacle Bot removed cli CLI command changes scripts Repository scripts extensions: qa-lab labels May 17, 2026

giodl73-repo marked this pull request as ready for review May 17, 2026 22:24

clawsweeper Bot added the rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. label May 18, 2026

giodl73-repo force-pushed the doctor-detection-conversion-plan branch from 84211f3 to 84a7dd0 Compare May 18, 2026 14:49

openclaw-barnacle Bot removed docs Improvements or additions to documentation gateway Gateway runtime labels May 18, 2026

clawsweeper Bot added status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed impact:session-state Session, memory, transcript, context, or agent state can drift or corrupt. labels May 18, 2026

clawsweeper Bot added the merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. label May 18, 2026

giodl73-repo and others added 4 commits May 18, 2026 11:42

feat(doctor): convert read-only health checks

9de2f50

fix(doctor): keep read-only conversion gates green

e363047

fix(doctor): preserve health repair preview contract

1d90ab3

fix(doctor): defer session snapshot lint target

3c33110

giodl73-repo force-pushed the doctor-detection-conversion-plan branch from 549459a to 3c33110 Compare May 18, 2026 18:43

Gio Della-Libera added 2 commits May 18, 2026 12:16

fix(doctor): avoid false-clean lint placeholders

e24823c

test(doctor): type conversion target registry check

1c8558a

giodl73-repo merged commit 94abfa7 into openclaw:main May 18, 2026
125 of 131 checks passed

giodl73-repo mentioned this pull request May 18, 2026

Doctor: normalize repair checks inside runner #83753

Merged

github-actions Bot mentioned this pull request May 18, 2026

📡 Upstream Digest — 2026-05-18 21:03 UTC curtismercier/openclaw-mods#893

Open

clawsweeper Bot mentioned this pull request May 24, 2026

[Bug]: Memory detection skips macOS (darwin) — os.freemem() / os.totalmem() never reported to agent on non-Linux platforms #47273

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Doctor: convert read-only health checks#83198

Doctor: convert read-only health checks#83198
giodl73-repo merged 6 commits into
openclaw:mainfrom
giodl73-repo:doctor-detection-conversion-plan

giodl73-repo commented May 17, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 17, 2026 •

edited

Loading

Uh oh!

giodl73-repo commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 •

edited

Loading

Uh oh!

giodl73-repo commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

giodl73-repo commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Behavior addressed

Migration rule

Staging note

Real behavior proof

Uh oh!

clawsweeper Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

giodl73-repo commented May 17, 2026 •

edited

Loading

clawsweeper Bot commented May 17, 2026 •

edited

Loading

clawsweeper Bot commented May 18, 2026 •

edited

Loading

clawsweeper Bot commented May 18, 2026 •

edited

Loading