@openclaw/plugin-inspector 0.3.19 → 0.3.20

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.20 - 2026-07-31
+
+### Added
+
+- Resolve `latest`, `beta`, or exact OpenClaw npm versions for compatibility inspection, reuse prepared targets from cache, and report exact target/source metadata.
+
+### Fixed
+
+- Treat version-derived API removals inside a plugin's declared OpenClaw range as author-facing errors while keeping out-of-range targets informational, including beta eligibility against the upcoming stable version.
+- Accept tested minimum OpenClaw host versions below a plugin's build version without reporting package metadata drift.
+- Ignore type-only OpenClaw SDK imports when classifying runtime compatibility against a target release.
+- Accept `openclaw.runtimeSetupEntry` and other paired compiled runtime entrypoints as valid replacements for absent source entrypoints.
+
 ## 0.3.19 - 2026-07-27
 
 ### Highlights

package/README.md

@@ -34,6 +34,12 @@ checkout. If an OpenClaw checkout is supplied with `--openclaw <path>`, the
 inspector only reads public compatibility surfaces such as compat records, SDK
 exports, hook names, manifest fields, and registrar metadata.
 
+Pass `--openclaw-version latest`, `--openclaw-version beta`, or an exact
+published version to resolve an official OpenClaw npm target. Reports keep the
+exact resolved version and npm source metadata. Prepared targets are cached, so
+batch and repeated inspections do not download the same OpenClaw package for
+each plugin.
+
 ## Quick Start
 
 Run this from a plugin package root:
@@ -181,6 +187,7 @@ Common options:
 | `--config <path>` | Read a standalone config file. Required for fixture-suite `report`. |
 | `--out <dir>` | Write reports somewhere other than `reports/`. |
 | `--openclaw <path>` | Compare against a local OpenClaw checkout. |
+| `--openclaw-version latest\|beta\|<exact>` | Resolve and compare against an official OpenClaw npm release. |
 | `--no-openclaw` | Disable OpenClaw checkout comparison. |
 | `--runtime` / `--capture` | Add opt-in runtime registration capture. |
 | `--no-runtime` / `--no-capture` | Disable runtime capture even when config enables it. |
@@ -298,7 +305,7 @@ Important report sections:
 | --- | --- |
 | `status` | `pass` unless hard breakages exist. |
 | `summary` | Counts for fixtures, breakages, warnings, suggestions, issues, issue classes, and contract probes. |
-| `targetOpenClaw` | Status and public compatibility data read from the optional OpenClaw checkout. |
+| `targetOpenClaw` | Exact resolved version, source metadata, cache state, and public compatibility data for the selected OpenClaw target. |
 | `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, SDK imports, and SDK deprecation evidence. |
 | `breakages` | Blocking compatibility failures. |
 | `warnings` / `suggestions` | Non-blocking compatibility findings. |
@@ -309,8 +316,9 @@ Important report sections:
 
 Default `check`, `ci`, and `batch` reports include both author-facing and
 internal findings. Pass `--author-facing` when producing plugin-author output;
-that filtered view includes only findings with `authorRemediation.summary` and
-`authorRemediation.docsUrl`.
+that filtered view includes only findings with `authorRemediation.summary`.
+Curated fixes include `authorRemediation.docsUrl`; dynamically discovered API
+removals use generic remediation without inventing a documentation URL.
 Current author-facing deprecation warnings include deprecated SDK helpers such
 as `loadSessionStore(...)` when a plugin still depends on the legacy whole-store
 session shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",
@@ -31,6 +31,7 @@
     "./execution-results": "./src/execution-results.js",
     "./import-loop-profile": "./src/import-loop-profile.js",
     "./openclaw-target": "./src/openclaw-target.js",
+    "./openclaw-version": "./src/openclaw-version.js",
     "./platform-probes": "./src/platform-probes.js",
     "./profile-diff": "./src/profile-diff.js",
     "./ref-diff": "./src/ref-diff.js",
@@ -69,5 +70,9 @@
     "plugin",
     "compatibility",
     "ci"
-  ]
+  ],
+  "dependencies": {
+    "semver": "^7.8.5",
+    "tar": "^7.5.22"
+  }
 }

package/src/advanced.js

@@ -116,6 +116,13 @@ export {
   parseTypeFields,
   readOpenClawTargetSurface,
 } from "./openclaw-target.js";
+export {
+  openClawEligibilityVersion,
+  prepareOpenClawTarget,
+  resolveOpenClawTargetVersion,
+  satisfiesOpenClawCompatibilityRange,
+  satisfiesOpenClawVersionRange,
+} from "./openclaw-version.js";
 export {
   captureEntrypoint,
   captureEntrypointWithMockSdk,

package/src/api.js

@@ -46,6 +46,7 @@ export async function inspectPluginRoot(options = {}) {
     authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     openclawPath: options.openclawPath,
+    openclawVersion: options.openclawVersion,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
   });
@@ -62,6 +63,7 @@ export async function inspectCompatibilityFixtureSetConfig(options = {}) {
     authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     openclawPath: options.openclawPath,
+    openclawVersion: options.openclawVersion,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
   });
@@ -117,6 +119,7 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
       authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
       openclawPath: options.openclawPath,
+      openclawVersion: options.openclawVersion,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
     }));
@@ -150,6 +153,7 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
       authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
       openclawPath: options.openclawPath,
+      openclawVersion: options.openclawVersion,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
     }));

package/src/batch.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { renderMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
 import { runPluginCheck } from "./api.js";
+import { prepareOpenClawTarget, resolveOpenClawTargetVersion } from "./openclaw-version.js";
 
 const ignoredDirs = new Set([
   ".git",
@@ -22,6 +23,11 @@ export async function runBatchAnalysis(options = {}) {
   const outRoot = path.resolve(rootDir, outDir);
   const concurrency = Math.max(1, Math.min(Math.round(options.concurrency ?? 4), 32));
   const keepPluginReports = options.keepPluginReports === true;
+  const targetOpenClaw =
+    options.targetOpenClaw ??
+    (options.openclawVersion
+      ? await prepareOpenClawTarget(await resolveOpenClawTargetVersion(options.openclawVersion, options), options)
+      : undefined);
   const pluginRoots = await discoverPluginRoots(rootDir);
   const tempRoot = keepPluginReports ? null : await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-batch-"));
   const entries = [];
@@ -37,6 +43,7 @@ export async function runBatchAnalysis(options = {}) {
           rootDir,
           outDir: reportsRoot,
           openclawPath: options.openclawPath,
+          targetOpenClaw,
         }),
       );
     });
@@ -113,6 +120,7 @@ async function inspectBatchPlugin(pluginRoot, options) {
       configPath: options.configPath,
       mockSdk: options.mockSdk,
       openclawPath: options.openclawPath,
+      targetOpenClaw: options.targetOpenClaw,
       outDir: options.outDir,
       pluginRoot,
     });

package/src/cli.js

@@ -57,9 +57,10 @@ try {
 }
 
 async function runBatch(commandArgs) {
-  const inputDir = readFirstPositional(commandArgs, new Set(["--out", "--openclaw", "--concurrency"]));
+  const inputDir = readFirstPositional(commandArgs, new Set(["--out", "--openclaw", "--openclaw-version", "--concurrency"]));
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const concurrency = Number(readFlag(commandArgs, "--concurrency") ?? "4");
   const json = commandArgs.includes("--json");
   const check = commandArgs.includes("--check");
@@ -72,6 +73,7 @@ async function runBatch(commandArgs) {
     rootDir: inputDir,
     outDir,
     openclawPath,
+    openclawVersion,
     concurrency,
     authorFacing,
     keepPluginReports,
@@ -105,6 +107,7 @@ async function runCheck(commandArgs, options = {}) {
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const json = commandArgs.includes("--json");
   const capture = readRuntimeFlag(commandArgs);
   const mockSdk = readMockSdkFlag(commandArgs);
@@ -118,6 +121,7 @@ async function runCheck(commandArgs, options = {}) {
     configPath,
     mockSdk,
     openclawPath,
+    openclawVersion,
     outDir,
     pluginRoot,
   });
@@ -169,15 +173,17 @@ async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
   const ciOutputs = readCiOutputFlags(commandArgs);
   const authorFacing = readAuthorFacingFlag(commandArgs);
   const config = await loadInspectorConfig(configPath);
-  const report = authorFacing
-    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath })
+  const compatibilityInspection = authorFacing || typeof openclawPath === "string" || openclawVersion !== null;
+  const report = compatibilityInspection
+    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath, openclawVersion })
     : await inspectFixtureSet(config);
-  const paths = authorFacing
+  const paths = compatibilityInspection
     ? await writeCompatibilityReport(report, { cwd: config.rootDir, outDir })
     : await writeReport(report, { outDir });
   await writeCiOutputArtifacts(report, {
@@ -202,6 +208,7 @@ async function runCi(commandArgs) {
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const json = commandArgs.includes("--json");
   const capture = readRuntimeFlag(commandArgs);
   const mockSdk = readMockSdkFlag(commandArgs);
@@ -215,6 +222,7 @@ async function runCi(commandArgs) {
     configPath,
     mockSdk,
     openclawPath,
+    openclawVersion,
     outDir,
     pluginRoot,
   });
@@ -256,12 +264,13 @@ async function runCiCompatibilityReport({
   configPath,
   mockSdk,
   openclawPath,
+  openclawVersion,
   outDir,
   pluginRoot,
 }) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
-    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath });
+    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath, openclawVersion });
     await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
     return {
       report,
@@ -275,6 +284,7 @@ async function runCiCompatibilityReport({
     capture,
     mockSdk,
     openclawPath,
+    openclawVersion,
     outDir,
     pluginRoot,
   });
@@ -314,6 +324,19 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function readOpenClawVersion(commandArgs) {
+  const index = commandArgs.indexOf("--openclaw-version");
+  if (index === -1) return null;
+  const version = commandArgs[index + 1];
+  if (!version || version.startsWith("-")) {
+    throw new Error("--openclaw-version requires a value");
+  }
+  if (version && (commandArgs.includes("--no-openclaw") || commandArgs.includes("--openclaw"))) {
+    throw new Error("--openclaw-version cannot be combined with --openclaw or --no-openclaw");
+  }
+  return version;
+}
+
 function findCaptureEntrypoint(commandArgs) {
   const flagsWithValues = new Set(["--output", "--plugin-root", "--sdk"]);
   const consumedIndexes = new Set();
@@ -452,13 +475,13 @@ function printHelp() {
 
 Usage:
   plugin-inspector
-  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
   plugin-inspector config [--plugin-root <path>] [--config <path>] [--json]
   plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--scripts] [--package-manager npm|pnpm|yarn|bun] [--dry-run] [--json] [--force]
-  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json]
-  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
-  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
-  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--author-facing] [--check] [--json]
+  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
+  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
   plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--allow-execute] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.

package/src/compatibility-report.js

@@ -351,6 +351,12 @@ function targetOpenClawTable(targetOpenClaw = {}) {
     [
       ["Configured path", targetOpenClaw.configuredPath ?? "-"],
       ["Status", targetOpenClaw.status],
+      ["Requested version", targetOpenClaw.requestedVersion ?? "-"],
+      ["Resolved version", targetOpenClaw.version ?? "-"],
+      ["Range eligibility version", targetOpenClaw.eligibilityVersion ?? "-"],
+      ["Source", targetOpenClaw.source ? `${targetOpenClaw.source.type}:${targetOpenClaw.source.package}` : "-"],
+      ["NPM dist-tag", targetOpenClaw.source?.distTag ?? "-"],
+      ["Prepared cache", targetOpenClaw.cache ? (targetOpenClaw.cache.hit ? "hit" : "miss") : "-"],
       ["Compat registry", targetOpenClaw.compatRegistryPath ?? "-"],
       ["Compat records", targetOpenClaw.compatRecordCount ?? 0],
       ["Compat status counts", Object.entries(statusCounts).map(([status, count]) => `${status}:${count}`).join(", ") || "-"],

package/src/config.js

@@ -195,7 +195,8 @@ async function readJsonIfExists(filePath) {
   if (!existsSync(filePath)) {
     return null;
   }
-  return JSON.parse(await readFile(filePath, "utf8"));
+  const contents = await readFile(filePath, "utf8");
+  return JSON.parse(contents.startsWith("\uFEFF") ? contents.slice(1) : contents);
 }
 
 export function packageId(packageName) {

package/src/fixture-summary.js

@@ -3,6 +3,7 @@ import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { compatRecordForIssueCode } from "./contract-probes.js";
 import { readJsonFile } from "./json-file.js";
+import { satisfiesOpenClawCompatibilityRange } from "./openclaw-version.js";
 
 const conversationAccessHooks = new Set(["agent_end", "llm_input", "llm_output"]);
 const captureGapRegistrations = new Set([
@@ -143,6 +144,8 @@ export function summarizePackage(packagePath, packageJson, options = {}) {
         extensions: arrayValues(packageJson.openclaw.extensions),
         runtimeExtensions: arrayValues(packageJson.openclaw.runtimeExtensions),
         setupEntry: typeof packageJson.openclaw.setupEntry === "string" ? packageJson.openclaw.setupEntry : null,
+        runtimeSetupEntry:
+          typeof packageJson.openclaw.runtimeSetupEntry === "string" ? packageJson.openclaw.runtimeSetupEntry : null,
         compatPluginApi:
           typeof packageJson.openclaw.compat?.pluginApi === "string" ? packageJson.openclaw.compat.pluginApi : null,
         buildOpenClawVersion:
@@ -464,30 +467,36 @@ export function classifyPackageContracts({ fixture, inspection, fixtureReport })
 }
 
 export function classifyTargetOpenClawCoverage({ fixture, inspection, fixtureReport, targetOpenClaw }) {
+  const breakages = [];
   const warnings = [];
+  const suggestions = [];
   const logs = [];
   const decisions = [];
+  const findingContext = { breakages, warnings, suggestions, fixtureReport, targetOpenClaw };
 
-  classifyHookNameCoverage({ fixture, inspection, targetOpenClaw, warnings, logs });
-  classifyRegistrationNameCoverage({ fixture, inspection, targetOpenClaw, warnings, logs });
-  classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions });
+  classifyHookNameCoverage({ fixture, inspection, targetOpenClaw, logs, findingContext });
+  classifyRegistrationNameCoverage({ fixture, inspection, targetOpenClaw, logs, findingContext });
+  classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions, findingContext });
   classifyManifestFieldCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions });
 
-  return { warnings, logs, decisions };
+  return { breakages, warnings, suggestions, logs, decisions };
 }
 
 export function classifyCompatibilityFixture({ fixture, inspection, fixtureReport, targetOpenClaw }) {
+  const breakages = [];
   const warnings = [];
   const suggestions = [];
   const logs = [];
   const decisions = [];
 
   if (inspection.status !== "ok") {
-    return { warnings, suggestions, logs, decisions };
+    return { breakages, warnings, suggestions, logs, decisions };
   }
 
   const targetCoverage = classifyTargetOpenClawCoverage({ fixture, inspection, fixtureReport, targetOpenClaw });
+  breakages.push(...targetCoverage.breakages);
   warnings.push(...targetCoverage.warnings);
+  suggestions.push(...targetCoverage.suggestions);
   logs.push(...targetCoverage.logs);
   decisions.push(...targetCoverage.decisions);
 
@@ -701,7 +710,7 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
     });
   }
 
-  return { warnings, suggestions, logs, decisions };
+  return { breakages, warnings, suggestions, logs, decisions };
 }
 
 function classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings, decisions }) {
@@ -807,7 +816,7 @@ function registrationCaptureGapDetails(inspection, targetOpenClaw) {
   return apiRegistrationDetails.filter((registration) => captureGapRegistrations.has(registration.name));
 }
 
-function classifyHookNameCoverage({ fixture, inspection, targetOpenClaw, warnings, logs }) {
+function classifyHookNameCoverage({ fixture, inspection, targetOpenClaw, logs, findingContext }) {
   if (targetOpenClaw.status !== "ok" || targetOpenClaw.hookNames.length === 0) {
     return;
   }
@@ -825,16 +834,18 @@ function classifyHookNameCoverage({ fixture, inspection, targetOpenClaw, warning
     return;
   }
 
-  warnings.push({
+  addVersionDerivedFinding({
+    ...findingContext,
+    finding: {
     fixture: fixture.id,
     code: "unknown-hook-name",
-    level: "warning",
     message: "fixture registers hooks that are not present in the target OpenClaw hook registry",
     evidence: detailEvidence(unknownHooks),
+    },
   });
 }
 
-function classifyRegistrationNameCoverage({ fixture, inspection, targetOpenClaw, warnings, logs }) {
+function classifyRegistrationNameCoverage({ fixture, inspection, targetOpenClaw, logs, findingContext }) {
   if (targetOpenClaw.status !== "ok" || targetOpenClaw.apiRegistrars.length === 0) {
     return;
   }
@@ -855,16 +866,18 @@ function classifyRegistrationNameCoverage({ fixture, inspection, targetOpenClaw,
     return;
   }
 
-  warnings.push({
+  addVersionDerivedFinding({
+    ...findingContext,
+    finding: {
     fixture: fixture.id,
     code: "unknown-registration-name",
-    level: "warning",
     message: "fixture calls api.register* methods that are not present in the target OpenClaw plugin API builder",
     evidence: detailEvidence(unknownRegistrations),
+    },
   });
 }
 
-function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions }) {
+function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions, findingContext }) {
   if (targetOpenClaw.status !== "ok" || targetOpenClaw.sdkExports.length === 0 || fixtureReport.sdkImports.length === 0) {
     return;
   }
@@ -888,13 +901,15 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
   }
 
   if (unknownImports.length > 0) {
-    warnings.push({
+    addVersionDerivedFinding({
+      ...findingContext,
+      finding: {
       fixture: fixture.id,
       code: "sdk-export-missing",
-      level: "warning",
       message: "fixture imports plugin SDK aliases that are not exported by the target OpenClaw package",
       evidence: detailEvidence(unknownImports, "specifier"),
       compatRecord: "plugin-sdk-export-aliases",
+      },
     });
     decisions.push({
       fixture: fixture.id,
@@ -923,6 +938,52 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
   }
 }
 
+function addVersionDerivedFinding({ finding, fixtureReport, targetOpenClaw, breakages, warnings, suggestions }) {
+  const compatibility = targetCompatibility(fixtureReport, targetOpenClaw);
+  if (!compatibility) {
+    warnings.push({ ...finding, level: "warning" });
+    return;
+  }
+
+  if (compatibility.inDeclaredRange) {
+    breakages.push({
+      ...finding,
+      level: "breakage",
+      compatibility,
+      authorRemediation: {
+        summary:
+          "Update the plugin to use APIs available in the target OpenClaw version, or narrow its declared compatibility range.",
+      },
+      authorRemediationDocs: false,
+    });
+    return;
+  }
+
+  suggestions.push({
+    ...finding,
+    level: "information",
+    message: `${finding.message}; the resolved target is outside the plugin's declared compatibility range`,
+    compatibility,
+  });
+}
+
+function targetCompatibility(fixtureReport, targetOpenClaw) {
+  const declaredRange = fixtureReport.package?.openclaw?.compatPluginApi;
+  const targetVersion = targetOpenClaw.version;
+  const evaluatedVersion = targetOpenClaw.eligibilityVersion ?? targetOpenClaw.version;
+  if (!declaredRange || !targetVersion || !evaluatedVersion || !targetOpenClaw.requestedVersion) return null;
+  return {
+    declaredRange,
+    targetVersion,
+    evaluatedVersion,
+    inDeclaredRange: satisfiesOpenClawCompatibilityRange({
+      targetVersion,
+      eligibilityVersion: evaluatedVersion,
+      range: declaredRange,
+    }),
+  };
+}
+
 function classifyManifestFieldCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions }) {
   if (targetOpenClaw.status !== "ok" || targetOpenClaw.manifestFields.length === 0) {
     return;
@@ -984,6 +1045,9 @@ function collectOpenClawEntrypoints(packageDir, openclaw, options) {
     ...openclaw.extensions.map((specifier) => ({ kind: "extension", specifier })),
     ...openclaw.runtimeExtensions.map((specifier) => ({ kind: "runtimeExtension", specifier })),
     ...(openclaw.setupEntry ? [{ kind: "setupEntry", specifier: openclaw.setupEntry }] : []),
+    ...(openclaw.runtimeSetupEntry
+      ? [{ kind: "runtimeSetupEntry", specifier: openclaw.runtimeSetupEntry }]
+      : []),
   ];
 
   return entrypoints.map((entrypoint) => {
@@ -1015,7 +1079,7 @@ function hasUsablePackageRuntimeEntrypoint(entrypoint, packageSummary, entrypoin
     return true;
   }
 
-  if (entrypoint.kind === "extension" && entrypoints.some((candidate) => candidate.kind === "runtimeExtension" && candidate.exists)) {
+  if (entrypoints.some((candidate) => candidate.exists && isPairedRuntimeEntrypoint(entrypoint, candidate))) {
     return true;
   }
 
@@ -1038,6 +1102,13 @@ function normalizeEntrypointSpecifier(specifier) {
   return normalized.startsWith("./") ? normalized : `./${normalized}`;
 }
 
+function isPairedRuntimeEntrypoint(entrypoint, candidate) {
+  return (
+    (entrypoint.kind === "extension" && candidate.kind === "runtimeExtension") ||
+    (entrypoint.kind === "setupEntry" && candidate.kind === "runtimeSetupEntry")
+  );
+}
+
 async function findPackageFiles(root, options, depth = 0) {
   if (!existsSync(root) || depth > options.maxDepth) {
     return [];
@@ -1227,9 +1298,10 @@ function hasPackagedRuntimeEntrypoint(entrypoint, packageSummary, entrypoints) {
   }
 
   if (
-    entrypoint.kind === "extension" &&
     entrypoints.some(
-      (candidate) => candidate.kind === "runtimeExtension" && repoPathIncludedInNpmPack(packageSummary, candidate.relativePath),
+      (candidate) =>
+        isPairedRuntimeEntrypoint(entrypoint, candidate) &&
+        repoPathIncludedInNpmPack(packageSummary, candidate.relativePath),
     )
   ) {
     return true;
@@ -1245,12 +1317,82 @@ function packageMinHostVersionDrift(packageSummary) {
   if (!nonEmptyString(openclaw?.install?.minHostVersion) || !nonEmptyString(openclaw?.buildOpenClawVersion)) {
     return false;
   }
-  return parseMinHostVersionFloor(openclaw.install.minHostVersion) !== openclaw.buildOpenClawVersion;
+  const minimumHostVersion = parseMinHostVersionFloor(openclaw.install.minHostVersion);
+  const buildOpenClawVersion = parseSemver(openclaw.buildOpenClawVersion);
+  if (!minimumHostVersion || !buildOpenClawVersion) {
+    return true;
+  }
+  return compareSemver(minimumHostVersion, buildOpenClawVersion) > 0;
 }
 
 function parseMinHostVersionFloor(value) {
   const match = /^>=([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/.exec(value);
-  return match?.[1] ?? null;
+  return match ? parseSemver(match[1]) : null;
+}
+
+function parseSemver(value) {
+  const match =
+    /^([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+      value,
+    );
+  if (!match) {
+    return null;
+  }
+  const coreParts = match.slice(1, 4);
+  if (coreParts.some((part) => part.length > 1 && part.startsWith("0"))) {
+    return null;
+  }
+  const prerelease = match[4]?.split(".") ?? [];
+  if (prerelease.some((part) => /^[0-9]+$/.test(part) && part.length > 1 && part.startsWith("0"))) {
+    return null;
+  }
+  return { core: coreParts, prerelease };
+}
+
+function compareNumericIdentifier(left, right) {
+  if (left.length !== right.length) {
+    return left.length < right.length ? -1 : 1;
+  }
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function compareSemver(left, right) {
+  for (let index = 0; index < left.core.length; index += 1) {
+    const comparison = compareNumericIdentifier(left.core[index], right.core[index]);
+    if (comparison !== 0) {
+      return comparison;
+    }
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    if (left.prerelease.length === right.prerelease.length) {
+      return 0;
+    }
+    return left.prerelease.length === 0 ? 1 : -1;
+  }
+  const count = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < count; index += 1) {
+    const leftPart = left.prerelease[index];
+    const rightPart = right.prerelease[index];
+    if (leftPart === undefined || rightPart === undefined) {
+      return leftPart === undefined ? -1 : 1;
+    }
+    if (leftPart === rightPart) {
+      continue;
+    }
+    const leftNumeric = /^[0-9]+$/.test(leftPart);
+    const rightNumeric = /^[0-9]+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      return compareNumericIdentifier(leftPart, rightPart);
+    }
+    if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    }
+    return leftPart < rightPart ? -1 : 1;
+  }
+  return 0;
 }
 
 function repoPathIncludedInNpmPack(packageSummary, repoPath) {