Skip to content

Doctor: normalize repair checks inside runner#83753

Merged
giodl73-repo merged 1 commit into
openclaw:mainfrom
giodl73-repo:doctor-detection-interactive-maintenance
May 23, 2026
Merged

Doctor: normalize repair checks inside runner#83753
giodl73-repo merged 1 commit into
openclaw:mainfrom
giodl73-repo:doctor-detection-interactive-maintenance

Conversation

@giodl73-repo

@giodl73-repo giodl73-repo commented May 18, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR narrows the first doctor repair migration step to the core doctor runner.

  • Adds an internal normalized health-check shape so the repair runner can execute either the existing split detect() / repair() checks or an internal single-flow run(ctx) check.
  • Keeps the public plugin SDK health contract unchanged: plugin authors still see detect() plus optional repair(), and no plugin SDK baseline is regenerated.
  • Preserves the old split-check repair sequencing so detected findings are still reported if repair() throws.
  • Threads dry-run, diff, repair effects, warnings, config updates, and post-repair validation through the normalized runner path.
  • Adds focused lint and repair-flow tests covering run-mode checks, split-check adaptation, dry-run/diff preview behavior, repair status mapping, repair failure reporting, and validation after successful repair.

The goal is to make the runner easier to migrate safely without asking every existing doctor check author to split one boolean repair flow immediately. Existing split checks still work through the adapter; internal checks can move to one flow when that is clearer.

Verification

Local/WSL proof:

  • git diff --check
  • OPENCLAW_OXLINT_SKIP_PREPARE=1 node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json src/flows/doctor-lint-flow.test.ts src/flows/doctor-repair-flow.test.ts src/flows/doctor-repair-flow.ts src/flows/health-check-adapter.ts src/flows/health-check-runner-types.ts
  • node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-prod-83753.tsbuildinfo
  • node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test-83753-pr1-contract.tsbuildinfo
  • Earlier focused Vitest after adding the split repair-failure regression test: node scripts/run-vitest.mjs src/flows/doctor-repair-flow.test.ts src/flows/doctor-lint-flow.test.ts — 2 files / 14 tests passed

Crabbox real CLI proof on current head:

Crabbox transcript excerpt, with temp home redacted:

HEAD=d139d39e884019ce5de521660ba382a0499a1575
NODE=v24.15.0
PNPM=11.2.2
CONFIG=<temp-home>/.openclaw/openclaw.json
LEGACY_BEFORE=present
== doctor --lint before ==
{"ok":false,"checksRun":1,"checksSkipped":16,"findings":[{"checkId":"core/doctor/browser-clawd-profile-residue","severity":"warning","message":"Legacy managed browser profile residue was found at <temp-home>/.openclaw/browser/clawd.","path":"<temp-home>/.openclaw/browser/clawd","ocPath":"oc://state/browser/clawd","fixHint":"Run `openclaw doctor --fix` to archive the stale clawd profile safely instead of deleting it in place."}]}
== doctor --fix ==
Archived legacy clawd managed browser profile residue.
- legacy profile: <temp-home>/.openclaw/browser/clawd
- canonical profile: <temp-home>/.openclaw/browser/openclaw/user-data
LEGACY_AFTER=absent
== doctor --lint after ==
{"ok":true,"checksRun":1,"checksSkipped":16,"findings":[]}

Real behavior proof

Behavior addressed: Doctor repair runner now has one internal normalized execution path while preserving existing split-check repair error behavior, lint behavior, repair behavior, dry-run/diff previews, effects, warnings, config updates, and validation behavior.

Real environment tested: AWS Crabbox Linux VM (cbx_cb0b70795a87) from current PR head d139d39e884019ce5de521660ba382a0499a1575.

Exact steps or command run after this patch: created a disposable OPENCLAW_HOME with legacy browser/clawd residue, ran doctor --lint --only core/doctor/browser-clawd-profile-residue --json, ran doctor --fix --yes --non-interactive --no-workspace-suggestions, then reran the same lint check.

Evidence after fix: before lint reported core/doctor/browser-clawd-profile-residue; doctor --fix archived the legacy clawd browser profile residue; after lint returned {"ok":true,"checksRun":1,"checksSkipped":16,"findings":[]}.

Observed result after fix: the public plugin SDK health surface remains unchanged, the core doctor runner adapts split checks and internal run checks, and a real repair-backed converted doctor check works through CLI lint/fix/lint on the pushed head.

What was not tested: full release/package acceptance lanes; this PR does not touch package installation or plugin SDK exports.

@openclaw-barnacle openclaw-barnacle Bot added commands Command implementations size: L maintainer Maintainer-authored PR labels May 18, 2026
@clawsweeper

clawsweeper Bot commented May 18, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge.

Latest ClawSweeper review: 2026-05-23 14:43 UTC / May 23, 2026, 10:43 AM ET.

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.

PR Surface
Source +287, Tests +232. Total +519 across 5 files.

View PR surface stats
Area Files Added Removed Net
Source 3 334 47 +287
Tests 2 243 11 +232
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 5 577 58 +519

Summary
The PR refactors the Doctor repair runner to normalize existing split detect()/repair() checks and internal single-flow run(ctx) checks behind an internal adapter, with focused tests and live CLI proof.

Reproducibility: not applicable. This is an internal Doctor runner refactor rather than a reported bug; source review, focused tests, CI signal, and the PR body's Crabbox CLI proof are the relevant checks.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Good normal PR quality with strong live CLI proof for the compatibility path and focused tests for the new internal path, pending owner acceptance.

Rank-up moves:

  • Get Doctor owner confirmation that the internal run(ctx) contract is the intended base for dependent repair-migration work.
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.

Real behavior proof
Sufficient (live_output): The PR body includes redacted AWS Crabbox live CLI lint/fix/lint output on head d139d39 showing a real Doctor repair path through the normalized runner.

Risk before merge

  • The protected maintainer label means the PR needs explicit maintainer handling before merge or closure.
  • The internal run(ctx) contract can become the base for follow-up Doctor repair migrations, so owner acceptance matters even though the public plugin SDK split contract is unchanged.
  • doctor --fix is a setup and recovery surface; regressions in sequencing, status mapping, dry-run preview, or validation can reduce repair availability.
  • Live CLI proof covers a real split/converted repair path, while the new single-run path is covered by focused tests rather than a production converted check.

Maintainer options:

  1. Merge after Doctor owner sign-off (recommended)
    If the Doctor owner accepts the internal run(ctx) migration base and current proof level, land with the compatibility and recovery-flow risk explicitly owned.
  2. Ask for broader repair smoke proof
    Require one more fresh-install or upgrade-style doctor --fix smoke if maintainers want wider recovery-path confidence before accepting the runner rewrite.
  3. Pause the repair migration stack
    Hold this PR and dependent Doctor repair-migration work if the internal repair contract should be redesigned together.

Next step before merge
Doctor owner review is the remaining action for a protected, compatibility-sensitive runner contract; there is no narrow automation repair to queue.

Security
Cleared: The diff only changes Doctor TypeScript source and tests, with no dependency, workflow, lockfile, package-resolution, secret-handling, or downloaded-code execution changes.

Review details

Best possible solution:

Keep the normalized runner internal, preserve the public plugin SDK split contract, and merge only after the Doctor owner accepts the internal run-contract direction and current coverage level.

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

Not applicable. This is an internal Doctor runner refactor rather than a reported bug; source review, focused tests, CI signal, and the PR body's Crabbox CLI proof are the relevant checks.

Is this the best way to solve the issue?

Unclear pending owner decision. The implementation is a plausible bounded refactor that keeps the public SDK stable and preserves split-check behavior, but the new internal run(ctx) contract is exactly the design point the PR discussion asks a Doctor reviewer to accept.

Label justifications:

  • P2: This is a bounded but important Doctor repair-runner refactor with limited blast radius outside setup and recovery flows.
  • merge-risk: 🚨 compatibility: The PR changes the internal execution contract that adapts existing split health checks and future runnable checks, so migration compatibility needs owner acceptance.
  • merge-risk: 🚨 availability: doctor --fix is a recovery path, and runner regressions could prevent or misreport repairs even when normal CI is green.
  • rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🦞 diamond lobster, patch quality is 🐚 platinum hermit, and Good normal PR quality with strong live CLI proof for the compatibility path and focused tests for the new internal path, pending owner acceptance.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes redacted AWS Crabbox live CLI lint/fix/lint output on head d139d39 showing a real Doctor repair path through the normalized runner.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted AWS Crabbox live CLI lint/fix/lint output on head d139d39 showing a real Doctor repair path through the normalized runner.

What I checked:

  • Live PR state: The live PR is open, non-draft, mergeable, and labeled maintainer, proof: sufficient, P2, merge-risk: 🚨 compatibility, and merge-risk: 🚨 availability; it changes 5 Doctor source/test files with +577/-58 lines. (d139d39e8840)
  • Normalized repair runner path: The PR normalizes repair checks once at runner entry, then dispatches by sourceContract so existing split checks and new internal run checks share the aggregate result path. (src/flows/doctor-repair-flow.ts:38, d139d39e8840)
  • Split-check compatibility: The split-check branch still detects first, preserves findings when repair throws, applies returned config only outside dry-run, and validates successful repairs with a scoped second detect call. (src/flows/doctor-repair-flow.ts:90, d139d39e8840)
  • Internal adapter boundary: The new adapter keeps split checks as sourceContract: "split" and wraps runnable checks with a detect shim; current main has no sourceContract, RunnableHealthCheck, or normalizeHealthCheck surface before this PR. (src/flows/health-check-adapter.ts:8, d139d39e8840)
  • Focused test coverage: The PR adds tests for single-run repair plus validation, split-check repair throws preserving findings, dry-run/diff threading, skipped repair status, and validation of remaining findings. (src/flows/doctor-repair-flow.test.ts:21, d139d39e8840)
  • Real behavior proof: The PR body and author comment provide current-head AWS Crabbox live CLI proof on head d139d39: lint found legacy browser residue, doctor --fix archived it, and the same lint check returned clean. (d139d39e8840)

Likely related people:

  • giodl73-repo: Merged PR history shows this account introduced the Doctor health-check contract and repair runner surface in Doctor: add health-check contract and --lint validation #80055 and later touched adjacent Doctor health-contribution paths. (role: introduced behavior and recent area contributor; confidence: high; commits: 9a5f2f61e76f, 94abfa76e21f, cbf72e5e26ee; files: src/flows/doctor-repair-flow.ts, src/flows/health-checks.ts, src/flows/doctor-health-contributions.ts)
  • steipete: Recent history on src/flows/doctor-health-contributions.ts includes update-handoff and Doctor repair-adjacent work, making this account a useful reviewer for repair sequencing and upgrade behavior. (role: adjacent Doctor/update repair contributor; confidence: medium; commits: aec0c56386e2, 7acbb2260c4a, 694ca50e9775; files: src/flows/doctor-health-contributions.ts, docs/gateway/doctor.md)
  • galiniliev: The PR discussion explicitly asks this account to review the Doctor repair-contract shape based on prior policy/Doctor boundary feedback. (role: requested reviewer; confidence: medium; files: src/flows/doctor-repair-flow.ts, src/flows/health-check-adapter.ts)

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

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. labels May 18, 2026
@giodl73-repo
giodl73-repo force-pushed the doctor-detection-interactive-maintenance branch from 0d39d29 to a6a9874 Compare May 18, 2026 21:24
@giodl73-repo

Copy link
Copy Markdown
Contributor Author

Fixed the P1 around optional shell completion lint noise.

Verification:

  • node node_modules/vitest/vitest.mjs run src/flows/doctor-core-checks.test.ts src/commands/doctor-completion.test.ts --reporter=verbose — 2 files / 12 tests passed
  • git diff --check origin/main...HEAD — passed

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 18, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

Updated the PR body with real WSL CLI proof for the shell-completion lint path after the P1 fix:

pnpm openclaw doctor --lint --only core/doctor/shell-completion --json

Observed result:

{"ok":true,"checksRun":1,"checksSkipped":19,"findings":[]}

@clawsweeper re-review

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. labels May 18, 2026
@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Fixed the P1 by preserving the late legacy systemd linger repair pass after doctor:gateway-services. The structured systemd check still runs early, but the post-gateway-services contribution remains available during doctor --fix for services that are loaded or repaired later in the same run.

Verification:

  • node node_modules/vitest/vitest.mjs run src/flows/doctor-health-contributions.test.ts src/flows/doctor-core-checks.test.ts src/commands/systemd-linger.test.ts src/flows/doctor-repair-flow.test.ts --reporter=dot
  • git diff --check

@clawsweeper

clawsweeper Bot commented May 18, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels May 18, 2026
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels May 22, 2026
@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper could not start a re-review for this item.

Reason: re-review requires an open issue or PR.

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Updated the PR body with current-head real Doctor CLI proof from AWS Crabbox.

Proof summary:

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

The prior current-head review run for this PR was cancelled before returning a verdict. Re-requesting once for current head d139d39e884019ce5de521660ba382a0499a1575; the PR body now includes AWS Crabbox real Doctor CLI proof for the converted browser residue repair path.

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

@giodl73-repo

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintainer Maintainer-authored PR merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: L status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants