openclaw - 💡(How to fix) Fix doctor: preflight check for secret-resolve apply-path shape coverage

Summary

Proposing a new doctor:secret-resolve-preflight health contribution that walks the user's secret target registry and warns on shape-coverage gaps the CLI's apply path can't handle.

Today, when the gateway emits a secret assignment for a target whose secretShape is sibling_ref and whose value path doesn't exist in source config, the CLI's resolveCommandSecretRefsViaGateway crashes via setPathExistingStrict ("Cannot set value at non-existent path"). PR #78555 fixes that specific instance by introducing a setPathCreateStrict path for sibling_ref. This issue asks the orthogonal question: should doctor also catch the general class proactively, so future shape additions don't reopen the same hole?

Motivation

The bug class is shape coverage drift — the gateway emits shapes the CLI's apply path hasn't grown a handler for. The user finds out by hitting a crash during openclaw status, openclaw channels list, or doctor itself, not by anything diagnosable from their config.

sibling_ref is the first concrete instance, but the same class can recur whenever a plugin registers a new secretShape or the gateway introduces a new resolution path the CLI hasn't switched on yet. Doctor is the natural place to surface this — it already loads the user's config and runs diagnose-only contributions for adjacent concerns (doctor:gateway-config, doctor:gateway-auth).

Proposed design

A new contribution doctor:secret-resolve-preflight, slotted right after doctor:gateway-auth in resolveDoctorHealthContributions(). For each target returned by discoverConfigSecretTargets(ctx.cfg):

• If secretShape === "sibling_ref" and getPath(ctx.cfg, target.pathSegments) === undefined → warn. Suggested remediation: upgrade to a CLI build that resolves sibling_ref SecretRefs via setPathCreateStrict (i.e. a build including PR #78555 once merged).
• If secretShape is anything other than the values this CLI build recognizes (secret_input, sibling_ref) → warn with the path + the unrecognized shape. Defense-in-depth for future shape additions that ship in the gateway before the matching CLI handler lands.

It does not mutate the config — the user's config is correct; the remediation is always a CLI upgrade.

Draft

A draft implementation is on a fork branch for evaluation: https://github.com/octocore-autonomous-systems/openclaw/tree/feat/doctor-secret-resolve-preflight (commit 27898c0f6f)

Diff: +51 lines in src/flows/doctor-health-contributions.ts, +108 lines in src/flows/doctor-health-contributions.test.ts. No framework changes; six new tests covering registration ordering, empty-config, populated/absent value paths for both shape branches, and unknown-shape defense-in-depth. All tests pass locally on upstream/main. Happy to convert into a PR if maintainers prefer to evaluate at that surface.

Relationship to PR #78555

This is orthogonal to PR #78555. #78555 fixes the specific sibling_ref crash by changing the apply primitive; this proposal adds a defensive doctor surface for the general class. They don't conflict — merging this without #78555 just means doctor warns affected users while they wait for the fix, and merging both keeps doctor catching any future shape additions where the CLI handler list falls behind the gateway.

If you'd prefer a different remediation entirely (e.g. exhaustiveness-typed secretShape at the registry boundary so missing CLI handlers fail at build time), I'm equally happy to abandon this branch in favor of that direction — wanted to surface the proposal while the shape is fresh.