Doctor: expose state integrity findings by giodl73-repo · Pull Request #95979 · openclaw/openclaw

giodl73-repo · 2026-06-23T05:27:31Z

Summary

Exposes core/doctor/state-integrity as a structured Doctor health finding surface.
Maps existing state directory, storage-class, config permission, and runtime state-directory diagnostics into stable HealthFinding output.
Adds dry-run repair effects for the state-integrity issues while leaving real mutations in the legacy noteStateIntegrity Doctor path.
Keeps the structured check opt-in for lint by setting defaultEnabled: false; default doctor --lint behavior is unchanged, while doctor --lint --all and --only core/doctor/state-integrity include it.
Preserves independent config-file permission findings even when the OpenClaw state directory is missing.
Does not add or change config, plugin, or public SDK contract surface.

This is the next narrow structured Doctor rule slice after session artifacts. It intentionally keeps the existing Doctor state-integrity implementation authoritative for real doctor / doctor --fix behavior.

Stack

Rebased onto current main at 81e53202f2 after #96471 merged. Current branch head is d0fb93fa2f (fix(doctor): preserve config permission findings).

Validation

Current head d0fb93fa2f:

OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs run src/flows/doctor-health-contributions.test.ts src/flows/doctor-lint-flow.test.ts src/commands/doctor-state-integrity.test.ts --reporter=dot - 88 tests passed, 1 Windows-only permission-mode test skipped, across 2 Vitest shards
pnpm exec oxlint.CMD src/flows/doctor-health-contributions.ts src/flows/doctor-health-contributions.test.ts src/flows/doctor-lint-flow.ts src/flows/doctor-lint-flow.test.ts src/commands/doctor-state-integrity.ts src/commands/doctor-state-integrity.test.ts
pnpm exec oxfmt.CMD --check src/flows/doctor-health-contributions.ts src/flows/doctor-health-contributions.test.ts src/flows/doctor-lint-flow.ts src/flows/doctor-lint-flow.test.ts src/commands/doctor-state-integrity.ts src/commands/doctor-state-integrity.test.ts
pnpm tsgo:test:src
git diff --check

Real behavior proof

Behavior or issue addressed:
Structured Doctor state-integrity findings now surface existing missing state-directory diagnostics through core/doctor/state-integrity, and the structured repair adapter reports a dry-run effect for the same issue while real mutation remains owned by the legacy Doctor path. The structured check is opt-in for lint so default doctor --lint compatibility is preserved.

Real environment tested:
Windows source checkout at PR head d0fb93fa2f, using isolated temp state paths where needed, NO_COLOR=1, and OPENCLAW_DISABLE_AUTO_UPDATE=1. The lint-selection proof uses the source health-check runner because it directly proves default-vs---all selection without running unrelated lint checks. The focused CLI proof uses the public source CLI path with --only core/doctor/state-integrity.

Exact steps or command run after this patch:

Ran a source harness that resolved Doctor contribution checks, filtered to core/doctor/state-integrity, and called runDoctorLintChecks(...) once with default options and once with includeAllChecks: true.
Ran node scripts/run-node.mjs doctor --lint --json --only core/doctor/state-integrity against an isolated missing OPENCLAW_STATE_DIR.
Ran the structured repair source harness for the same isolated missing state directory with dryRun: true.

Evidence after fix:
Default-vs-all selection source harness:

{
  "default": {
    "checksRun": 0,
    "checksSkipped": 1
  },
  "all": {
    "checksRun": 1,
    "checksSkipped": 0
  },
  "defaultEnabled": false
}

Public CLI structured finding through explicit opt-in, redacted:

OPENCLAW_STATE_DIR=<TEMP_PROOF_ROOT>\missing-state
{"ok":false,"checksRun":1,"checksSkipped":27,"findings":[{"checkId":"core/doctor/state-integrity","severity":"error","message":"State directory is missing. Sessions, credentials, logs, and config are stored there.","path":"<TEMP_PROOF_ROOT>\\missing-state","fixHint":"Run `openclaw doctor --fix` to create the state directory."}]}
EXIT_CODE=1

Structured dry-run repair effect source harness, redacted:

{
  "findings": [
    {
      "checkId": "core/doctor/state-integrity",
      "severity": "error",
      "message": "State directory is missing. Sessions, credentials, logs, and config are stored there.",
      "path": "<TEMP_PROOF_ROOT>\\missing-state",
      "fixHint": "Run `openclaw doctor --fix` to create the state directory."
    }
  ],
  "repair": {
    "status": "repaired",
    "changes": [],
    "effects": [
      {
        "kind": "state",
        "action": "would-create-state-dir",
        "target": "<TEMP_PROOF_ROOT>\\missing-state",
        "dryRunSafe": false
      }
    ]
  }
}

Observed result after fix:
Default lint selection skips the state-integrity check. --all selection includes it. The explicit --only public lint command ran exactly one check, emitted one error finding for core/doctor/state-integrity, and exited 1. The structured repair adapter reported the matching would-create-state-dir effect without mutating the missing state directory.

What was not tested:
POSIX config permission live CLI output was not tested on this Windows host; that branch remains covered by the POSIX-only regression because Windows intentionally skips mode diagnostics. Command-wide dry-run report output was not tested because that public reporting surface is planned in #84472, not this PR.

Notes

The rebased diff is 4 files changed. The latest update resolves ClawSweeper's default-lint compatibility finding by making core/doctor/state-integrity opt-in for lint while preserving --all and --only access.

giodl73-repo · 2026-06-23T05:29:13Z

@clawsweeper review

Please review current head c39ead5c6049ff7560d8b513e179b79c15958fc9 for the new Doctor state-integrity structured findings slice. Real state mutations intentionally remain in the legacy noteStateIntegrity path; this PR only adds structured findings and dry-run effects.

clawsweeper · 2026-06-23T05:29:17Z

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

clawsweeper · 2026-06-23T19:25:05Z

Codex review: needs maintainer review before merge. Reviewed June 27, 2026, 11:24 AM ET / 15:24 UTC.

Summary
The PR adds an opt-in structured Doctor state-integrity health check, dry-run repair effects, and regression coverage while leaving real state repairs in the legacy Doctor path.

PR surface: Source +348, Tests +157. Total +505 across 4 files.

Reproducibility: not applicable. this is a structured Doctor surface rather than a bug report. The PR body provides terminal proof for the opt-in lint and dry-run paths.

Review metrics: 1 noteworthy metric.

Opt-in Doctor health check: 1 added. The PR expands the complete Doctor lint inventory for --all and explicit --only without changing default lint selection.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/commands/doctor-state-integrity.test.ts, migration/backfill/repair: src/commands/doctor-state-integrity.ts, migration/backfill/repair: src/flows/doctor-health-contributions.test.ts, migration/backfill/repair: src/flows/doctor-health-contributions.ts, unknown-data-model-change: src/commands/doctor-state-integrity.test.ts, unknown-data-model-change: src/commands/doctor-state-integrity.ts, and 1 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Let pending exact-head checks complete before merge.

Risk before merge

[P1] The protected maintainer label and assignee mean this PR should wait for explicit maintainer handling rather than automated cleanup or merge.
[P1] Some exact-head checks were still pending when inspected; merge should wait for required gates to finish.

Maintainer options:

Decide the mitigation before merge
Land the opt-in structured state-integrity check after maintainer approval and exact-head gates, while keeping legacy noteStateIntegrity authoritative for real repairs.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

[P2] Manual review is appropriate because the PR carries the protected maintainer label and needs final maintainer approval/gate completion, not a narrow automated repair.

Security
Cleared: No concrete security or supply-chain regression was found; the diff touches Doctor TypeScript/tests and maps existing permission diagnostics without changing dependencies, workflows, or secret handling.

Review details

Best possible solution:

Land the opt-in structured state-integrity check after maintainer approval and exact-head gates, while keeping legacy noteStateIntegrity authoritative for real repairs.

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

Not applicable; this is a structured Doctor surface rather than a bug report. The PR body provides terminal proof for the opt-in lint and dry-run paths.

Is this the best way to solve the issue?

Yes; the implementation mirrors adjacent structured Doctor slices, keeps the check default-disabled for lint compatibility, and leaves real mutations in the legacy state-integrity path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4010b81a77f4.

Label changes

Label changes:

add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes redacted terminal output for explicit Doctor lint selection and source-harness dry-run repair effects; the latest commit only stabilizes a test assertion.
remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

P2: This is a bounded Doctor CLI diagnostic improvement with limited blast radius, but it still needs maintainer handling before merge.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes redacted terminal output for explicit Doctor lint selection and source-harness dry-run repair effects; the latest commit only stabilizes a test assertion.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted terminal output for explicit Doctor lint selection and source-harness dry-run repair effects; the latest commit only stabilizes a test assertion.

Evidence reviewed

PR surface:

Source +348, Tests +157. Total +505 across 4 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	2	348	0	+348
Tests	2	158	1	+157
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	4	506	1	+505

What I checked:

Repository policy read: Root AGENTS.md was read fully; its protected-label and Doctor/config compatibility review guidance affected this keep-open review. (AGENTS.md:35, 4010b81a77f4)
Live PR state: Live GitHub metadata shows this PR is open, assigned to steipete, carries the protected maintainer label, is mergeable but UNSTABLE, and has head eb3bd1a. (eb3bd1adadde)
Current-main baseline: Current main still registers doctor:state-integrity as the legacy runStateIntegrityHealth contribution without a structured health check, so this PR is not already implemented on main. (src/flows/doctor-health-contributions.ts:1282, 4010b81a77f4)
PR implementation shape: PR head adds detectStateIntegrityHealthIssues plus closed finding and repair-effect mappers for state-dir, storage-class, config-permission, and runtime-dir issues. (src/commands/doctor-state-integrity.ts:760, eb3bd1adadde)
Opt-in lint compatibility: PR head registers core/doctor/state-integrity with defaultEnabled: false, preserving default doctor --lint selection while allowing --all and explicit --only. (src/flows/doctor-health-contributions.ts:1285, eb3bd1adadde)
Regression coverage: PR head now selects the missing-state-dir issue by kind and covers config permission findings even when the state directory is missing. (src/commands/doctor-state-integrity.test.ts:128, eb3bd1adadde)

Likely related people:

giodl73-repo: Prior merged Doctor health-check contract, read-only health conversion, and ordered contribution work established the pattern this PR extends. (role: recent structured Doctor contributor; confidence: high; commits: 9a5f2f61e76f, 94abfa76e21f, e56fd1dc0466; files: src/flows/doctor-health-contributions.ts, src/flows/doctor-lint-flow.ts, src/commands/doctor-session-transcripts.ts)
vincentkoc: Recent history added volatile and SD-backed state diagnostics in the same Doctor state-integrity module that this PR maps into structured findings. (role: state-integrity diagnostics contributor; confidence: high; commits: c9605779ef4a, 0c909ea97f20; files: src/commands/doctor-state-integrity.ts)
steipete: The live PR is assigned to steipete, and history shows prior Doctor state/flow refactors and docs in the affected area. (role: assigned reviewer and adjacent area contributor; confidence: medium; commits: f91de52f0d23, d4ac91d8f0df, c8665c66ba96; files: src/commands/doctor-state-integrity.ts, src/flows/doctor-health-contributions.ts, src/flows/doctor-lint-flow.ts)

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.

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.

giodl73-repo · 2026-06-24T01:05:39Z

@clawsweeper re-review

Current head 50feea3a2e addresses the state-integrity finding by preserving config-file permission diagnostics when the state dir is missing, while still gating child runtime-dir checks on the state dir existing. PR body has focused validation, the new combined regression, and source CLI proof notes.

clawsweeper · 2026-06-24T01:05:42Z

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

giodl73-repo · 2026-06-25T16:07:54Z

@clawsweeper re-review

Rebased after #95976 merged; current head is fe18439d0579061bf542972140454232c860a29e. Conflict was limited to the Doctor contribution ID test and resolved by keeping the already-merged sandbox, gateway-services, config-audit, session-transcripts, session-snapshots, and state-integrity IDs.

Validation refreshed in the PR body: focused state-integrity/contribution Vitest is green, changed-file oxfmt/oxlint are green, tsgo core/test-src are green, plugin SDK surface report is clean, and diff check is clean. No config, plugin, or public SDK contract change.

clawsweeper · 2026-06-25T16:07:58Z

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

giodl73-repo · 2026-06-25T21:38:32Z

@clawsweeper re-review

Current head 24d45fc5ae13e102bf799ce937b5cdd9d894e1a7 fixes the missing-state-dir regression expectation to match the actual mapper text. PR body now includes the required Real behavior proof section with captured/redacted public CLI output for doctor --lint --json --only core/doctor/state-integrity and a captured source-harness dry-run repair effect transcript. Focused state-integrity/contribution Vitest, changed-file oxfmt/oxlint, pnpm tsgo:test:src, and diff check passed.

clawsweeper · 2026-06-25T21:38:35Z

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

giodl73-repo · 2026-06-26T04:25:02Z

@clawsweeper re-review

Current head 109a54ec9ade190a3554ec640e402c1c6ff16bb5 fixes the CI check-lint failure by adding explicit exhaustive fallback returns for the state-integrity finding/effect mappers. Local validation passed: focused state-integrity/contribution Vitest, changed-file oxfmt --check, changed-file oxlint, full node scripts/run-oxlint-shards.mjs --threads=8, pnpm tsgo:test:src, and git diff --check. GitHub check-lint now passes on this head; the prior checks-node-compact-small-7 timeout also passes on the refreshed run.

clawsweeper · 2026-06-26T04:25:05Z

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

giodl73-repo · 2026-06-27T15:32:03Z

Merged via squash.

Prepared head SHA: eb3bd1adadde1040c520836a4683bbca10e943a9
Merge commit: cb4244fe15e30619423173ab746cc73e468b7346

Thanks @giodl73-repo!

openclaw-barnacle Bot added commands Command implementations size: M maintainer Maintainer-authored PR labels Jun 23, 2026

clawsweeper Bot added the merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. label Jun 24, 2026

giodl73-repo force-pushed the doctor-state-integrity-structured-repairs branch from 50feea3 to fe18439 Compare June 25, 2026 16:07

giodl73-repo force-pushed the doctor-state-integrity-structured-repairs branch from fe18439 to 24d45fc Compare June 25, 2026 21:37

giodl73-repo marked this pull request as ready for review June 26, 2026 03:35

giodl73-repo force-pushed the doctor-state-integrity-structured-repairs branch from 24d45fc to 109a54e Compare June 26, 2026 04:18

openclaw-barnacle Bot added size: XL and removed size: L labels Jun 27, 2026

giodl73-repo force-pushed the doctor-state-integrity-structured-repairs branch from 688361e to eb3bd1a Compare June 27, 2026 15:15

giodl73-repo mentioned this pull request Jun 27, 2026

Doctor: expose plugin registry findings #96169

Merged

github-actions Bot mentioned this pull request Jun 27, 2026

📡 Upstream Digest — 2026-06-27 16:59 UTC curtismercier/openclaw-mods#1160

Open

Uh oh!

Uh oh!

Conversation

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

Uh oh!

Summary

Stack

Validation

Real behavior proof

Notes

Uh oh!

giodl73-repo commented Jun 23, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

giodl73-repo commented Jun 24, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

giodl73-repo commented Jun 26, 2026

Uh oh!

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

Uh oh!

Uh oh!

giodl73-repo commented Jun 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

giodl73-repo commented Jun 23, 2026 •

edited

Loading

clawsweeper Bot commented Jun 23, 2026 •

edited

Loading

clawsweeper Bot commented Jun 23, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

giodl73-repo commented Jun 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 25, 2026 •

edited

Loading

giodl73-repo commented Jun 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 26, 2026 •

edited

Loading