Summary

openclaw doctor should detect stale session snapshots / cached metadata that still reference old runtime roots after OpenClaw has been moved, rewired, upgraded, or temporarily run from the wrong path.

This bit me through bundled skill paths, but the problem is broader than one skill.

Concrete failure mode

I diagnosed a case where:

• the live runtime was correct under:
  • ~/.openclaw/lib/node_modules/openclaw
• but the session's cached skillsSnapshot.prompt still referenced:
  • /opt/homebrew/lib/node_modules/openclaw/skills/github/SKILL.md

A fresh runtime-built snapshot resolved the correct bundled skill path.
The wrong path was coming from the cached session snapshot, not the live resolver.

Why it happens

OpenClaw stores session-cached prompt metadata such as skillsSnapshot.
When the runtime root changes, those cached absolute paths can become stale.

Current snapshot invalidation appears to depend on watched skill roots like workspace / managed / extraDirs / plugin dirs, but not bundled-skill runtime-root changes.

So users can end up with long-lived sessions that still carry bad absolute paths from:

• old install roots
• temp-backed builds
• debugging from /tmp or /private/tmp
• wrong-path local builds later repaired
• install-method changes (Homebrew/global/user-scoped)

Why doctor should catch it

From the user's perspective this looks like random path breakage:

• missing bundled skills
• wrong skill location in prompt/bootstrap metadata
• dead temp-path references surviving long after the runtime was fixed
• wasted debugging time because live runtime and cached session metadata disagree

This is exactly the sort of environment drift doctor should surface.

Proposed doctor checks

Add a diagnostic that:

1. resolves the active runtime root
2. scans session entries for cached snapshots/reports containing absolute paths under:
   • missing roots
   • non-current install roots
   • /tmp or /private/tmp
3. flags bundled-skill paths that do not match the active runtime root
4. reports the problem as stale cached session metadata, not just generic missing files
5. suggests or optionally offers safe remediation such as:
   • invalidate/rebuild affected snapshots
   • warn that long-lived sessions are carrying stale absolute paths

Acceptance criteria

• openclaw doctor warns when a session snapshot references bundled skills under an inactive runtime root
• openclaw doctor warns when cached metadata references deleted temp-backed runtime paths
• output distinguishes live runtime path is healthy vs cached session metadata is stale
• remediation guidance is explicit and safe

Related but distinct

This is adjacent to UI/path-resolution issues, but not the same class of bug.
This request is specifically about doctor detecting stale snapshot residue after runtime-path changes.

Environment where observed

• OpenClaw 2026.3.13
• macOS
• runtime lineage included old Homebrew/temp-backed paths, then repaired to user-scoped install under ~/.openclaw/lib/node_modules/openclaw