What this PR does

When loadPluginMetadataSnapshot is called more than once in the same OpenClaw process, an in-process cache (added in #81570) skips the expensive plugin discovery scan and reuses the previous snapshot. That cache currently keys on the registry index and a small set of environment inputs — so if a plugin's manifest, source files, or managed npm metadata change underneath without the registry index being touched, the second call can hand back a stale snapshot.

This PR widens what the cache notices. It now fingerprints the underlying watched files (plugin manifests, source/setup/package metadata, recovered managed npm packages, and install records under the home-relative path) so any direct change to those files invalidates the cache and forces a fresh snapshot. The hot path is preserved: when nothing has changed, the cache still hits without re-scanning.

Practically: editing a plugin's openclaw.plugin.json between two calls in the same process now produces an updated snapshot on the second call, instead of returning the cached pre-edit version.

AI-assisted: yes, with Codex.

Why this matters

Same-process snapshot reuse is the common case (CLI commands, gateway request handling, agent dispatch within one node process). Without watched-file freshness, three classes of change can be silently masked:

1. Plugin developers editing their own openclaw.plugin.json and re-running within the same OC session.
2. Managed npm packages that materialize after the first snapshot (e.g., a late install completes between calls).
3. Env-scoped state changes (HOME, OPENCLAW_*) where the cache shouldn't be reused across env contexts at all.

In each case, the registry index can stay byte-identical while the on-disk plugin metadata diverges from the cached snapshot.

Relationship to #81570

#81570 landed the perf hotfix for repeated in-process plugin metadata snapshots. This PR keeps that memo shape intact — it only widens the freshness key so persisted-registry cache hits also account for direct file changes. No reverts, no behavior change to the fast path when nothing has changed.

Scope

• 2 files changed: src/plugins/plugin-metadata-snapshot.ts (logic) + src/plugins/plugin-metadata-snapshot.memo.test.ts (regression coverage).
• The watched-file fingerprint is computed once when the cache misses, then reused on every subsequent same-process call until one of the watched files actually changes. The fast registry fingerprint runs first so unchanged-state lookups stay cheap.

Real behavior proof

Behavior or issue addressed: after #81570, loadPluginMetadataSnapshot could reuse a cached persisted snapshot in the same process even when persisted plugin metadata files, recovered managed npm package metadata, or env-scoped watched inputs changed underneath the accepted registry.

Real environment tested: local source worktree on Linux/WSL2 at PR head 2b8054330fa1df464e0e2c42a1f4ee7934f64898, rebased on origin/main c8228245039b777004de37d59eb69527fb060af7.

Exact steps or command run after this patch: env NODE_NO_WARNINGS=1 node --import tsx /tmp/openclaw-pr-81064-live-proof.mjs; pnpm -C <repo> test src/plugins/plugin-metadata-snapshot.memo.test.ts; pnpm -C <repo> format:check src/plugins/plugin-metadata-snapshot.ts src/plugins/plugin-metadata-snapshot.memo.test.ts; git -C <repo> diff --check.

Evidence after fix: the live proof harness created a temporary OpenClaw state directory, wrote a persisted plugin registry and real plugin manifest/package/source files, loaded loadPluginMetadataSnapshot, changed only openclaw.plugin.json while leaving plugins/installs.json unchanged, then called the real loader again. The second snapshot returned the changed command alias instead of the stale cached alias:

{
  "firstAlias": "proof-before",
  "secondAlias": "proof-after-metadata-change",
  "pluginCount": 1,
  "registryDiagnostics": [
    "persisted-registry-stale-source"
  ]
}

The targeted memo test suite also passed: 1 file, 20 tests, covering persisted plugin manifests, source/setup/package metadata, home-relative install-record paths, recovered managed npm package metadata, late-created managed package files, package.json symlink targets, and HOME/env-specific watched sets without clearing the process memo. format:check and diff --check also passed.

Observed result after fix: #81064 remains a 2-file follow-up that preserves #81570's process memo performance shape and adds the missing same-process freshness guarantees for persisted plugin metadata inputs.

What was not tested: beta6 CLI startup timing was not rerun for this recut because that performance hotfix is already landed via #81570; this PR is freshness hardening only.

Verification

• env NODE_NO_WARNINGS=1 node --import tsx /tmp/openclaw-pr-81064-live-proof.mjs — refreshed alias observed after unchanged-registry manifest mutation
• pnpm -C <repo> test src/plugins/plugin-metadata-snapshot.memo.test.ts — 1 file, 20 tests passed
• pnpm -C <repo> format:check src/plugins/plugin-metadata-snapshot.ts src/plugins/plugin-metadata-snapshot.memo.test.ts
• git -C <repo> diff --check
• Remote pnpm install + build:plugin-sdk:dts + tsgo:prod + check:test-types + memo test validation on GCP e2-standard-8 (Crabbox)