@openclaw/plugin-inspector 0.3.11 → 0.3.12

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.3.12 - 2026-06-09
+
+### Changed
+
+- Hide maintainer-facing `inspector-gap` findings from author-facing `check`, `ci`, and `batch` output by default, with `--include-inspector-gaps` for internal coverage reports.
+
 ## 0.3.11 - 2026-05-26
 
 ### Fixed

package/README.md

@@ -170,6 +170,7 @@ Copy-ready examples live in:
 | `plugin-inspector config` | Print resolved plugin-root config as text or JSON. |
 | `plugin-inspector init` | Write starter config, scripts, and optional GitHub Actions workflow. |
 | `plugin-inspector report` | Run a fixture-suite config with many plugins. |
+| `plugin-inspector batch` | Discover plugin roots under a folder and write one aggregate impact report. |
 | `plugin-inspector capture` | Runtime-capture one entrypoint directly. |
 
 Common options:
@@ -186,6 +187,7 @@ Common options:
 | `--mock-sdk` / `--sdk mock` | Use generated SDK and external-package mocks for runtime capture. |
 | `--real-sdk` / `--sdk real` | Use installed real SDK dependencies instead of mocks. |
 | `--allow-execute` | Permit commands that import plugin code. |
+| `--include-inspector-gaps` | Include maintainer-facing scanner coverage gaps in `check`, `ci`, and `batch` output. |
 | `--json` | Print machine-readable JSON to stdout. |
 | `--sarif [path]` | Write SARIF from `check` or `inspect`; `ci` enables this by default. |
 | `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
@@ -305,8 +307,9 @@ Important report sections:
 | `logs` | Informational inventory and coverage rows. |
 | `decisions` | Maintainer-facing follow-up or compatibility-policy decisions. |
 
-Issue classes currently flow through the reports as live issues, compat gaps,
-deprecation warnings, inspector gaps, upstream metadata, and fixture regressions.
+Author-facing `check`, `ci`, and `batch` output hides inspector gaps by default
+because they are scanner coverage backlog, not plugin-author fixes. Pass
+`--include-inspector-gaps` for Crabpot-style maintainer coverage reports.
 
 ## CI Policy And Shared Reporting Primitives
 
@@ -404,6 +407,7 @@ Stable grouped facades:
 | `reports` | Render/write reports and classify issue findings. |
 | `contracts` | Build, render, validate, and write contract captures and coverage. |
 | `ci` | Build summaries, policy reports, execution results, SARIF, and JUnit outputs. |
+| `batch` | Discover plugin roots and aggregate compatibility findings across a corpus. |
 | `runtime` | Build runtime profiles, profile diffs, ref diffs, and import-loop profiles. |
 | `synthetic` | Build and run synthetic probe plans. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/api.js

@@ -44,6 +44,7 @@ export async function inspectPluginRoot(options = {}) {
   const config = await loadPluginConfig(options);
   return inspectCompatibilityFixtureSet(config, {
     generatedAt: options.generatedAt,
+    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -59,6 +60,7 @@ export async function inspectCompatibilityFixtureSetConfig(options = {}) {
   const config = await loadFixtureSetConfig(options);
   return inspectCompatibilityFixtureSet(config, {
     generatedAt: options.generatedAt,
+    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -113,6 +115,7 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
       generatedAt: options.generatedAt,
+      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
@@ -145,6 +148,7 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
       generatedAt: options.generatedAt,
+      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,

package/src/batch.js

@@ -0,0 +1,297 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { renderMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { runPluginCheck } from "./api.js";
+
+const ignoredDirs = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "reports",
+  "dist",
+  "build",
+  ".plugin-inspector",
+]);
+
+export async function runBatchAnalysis(options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? options.inputDir ?? process.cwd());
+  const outDir = options.outDir ?? "reports";
+  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 pluginRoots = await discoverPluginRoots(rootDir);
+  const tempRoot = keepPluginReports ? null : await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-batch-"));
+  const entries = [];
+
+  try {
+    await runWithConcurrency(pluginRoots, concurrency, async (pluginRoot) => {
+      const reportsRoot = keepPluginReports
+        ? path.join(outRoot, "plugins", slugForPath(path.relative(rootDir, pluginRoot)))
+        : path.join(tempRoot, slugForPath(path.relative(rootDir, pluginRoot)));
+      entries.push(
+        await inspectBatchPlugin(pluginRoot, {
+          ...options,
+          rootDir,
+          outDir: reportsRoot,
+          openclawPath: options.openclawPath,
+        }),
+      );
+    });
+  } finally {
+    if (tempRoot) await rm(tempRoot, { recursive: true, force: true });
+  }
+
+  entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const report = buildBatchReport({
+    rootDir,
+    entries,
+    generatedAt: options.generatedAt ?? new Date().toISOString(),
+  });
+  const paths = await writeBatchReport(report, { outDir: outRoot, check: options.checkArtifacts });
+  return { report, paths };
+}
+
+export async function discoverPluginRoots(rootDir) {
+  const roots = [];
+  await walk(path.resolve(rootDir));
+  roots.sort();
+  return roots;
+
+  async function walk(dir) {
+    if (await isPluginRoot(dir)) {
+      roots.push(dir);
+      return;
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || ignoredDirs.has(entry.name)) continue;
+      await walk(path.join(dir, entry.name));
+    }
+  }
+}
+
+export async function writeBatchReport(report, options = {}) {
+  return writeJsonMarkdownArtifacts({
+    jsonPath: path.join(options.outDir ?? "reports", "plugin-inspector-batch-report.json"),
+    markdownPath: path.join(options.outDir ?? "reports", "plugin-inspector-batch-report.md"),
+    json: report,
+    markdown: renderBatchMarkdown(report),
+    check: options.check,
+  });
+}
+
+function buildBatchReport({ rootDir, entries, generatedAt }) {
+  const findingFrequency = findingFrequencyRows(entries);
+  const summary = {
+    pluginCount: entries.length,
+    passed: entries.filter((entry) => entry.status === "pass").length,
+    failed: entries.filter((entry) => entry.status !== "pass").length,
+    pluginsWithErrors: entries.filter((entry) => entry.errorCount > 0).length,
+    pluginsWithWarnings: entries.filter((entry) => entry.warningCount > 0).length,
+    errorCount: entries.reduce((sum, entry) => sum + entry.errorCount, 0),
+    warningCount: entries.reduce((sum, entry) => sum + entry.warningCount, 0),
+    findingCodeCount: findingFrequency.length,
+  };
+  return {
+    generatedAt,
+    rootDir,
+    summary,
+    findingFrequency,
+    plugins: entries,
+  };
+}
+
+async function inspectBatchPlugin(pluginRoot, options) {
+  try {
+    const { report } = await runPluginCheck({
+      allowExecution: options.allowExecution,
+      capture: options.capture,
+      configPath: options.configPath,
+      includeInspectorGaps: options.includeInspectorGaps,
+      mockSdk: options.mockSdk,
+      openclawPath: options.openclawPath,
+      outDir: options.outDir,
+      pluginRoot,
+    });
+    const findings = normalizeReportFindings(report);
+    return {
+      pluginRoot,
+      relativePath: path.relative(options.rootDir ?? process.cwd(), pluginRoot) || ".",
+      status: report.status,
+      packageName: packageNameFromReport(report),
+      targetOpenClaw: report.targetOpenClaw,
+      errorCount: findings.filter((finding) => finding.kind === "error").length,
+      warningCount: findings.filter((finding) => finding.kind === "warning").length,
+      findings,
+    };
+  } catch (error) {
+    return {
+      pluginRoot,
+      relativePath: path.relative(options.rootDir ?? process.cwd(), pluginRoot) || ".",
+      status: "error",
+      packageName: path.basename(pluginRoot),
+      targetOpenClaw: null,
+      errorCount: 1,
+      warningCount: 0,
+      findings: [
+        {
+          kind: "error",
+          code: "plugin-inspector-batch-failure",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+}
+
+function normalizeReportFindings(report) {
+  return [
+    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
+    ...(report.issues ?? []).map((finding) =>
+      normalizeFinding(
+        finding,
+        finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
+      ),
+    ),
+    ...(report.warnings ?? []).map((finding) => normalizeFinding(finding, "warning")),
+    ...(report.suggestions ?? []).map((finding) => normalizeFinding(finding, "warning")),
+  ];
+}
+
+function normalizeFinding(finding, kind) {
+  return {
+    kind,
+    code: finding.code ?? "plugin-inspector-finding",
+    severity: finding.severity,
+    issueClass: finding.issueClass,
+    message: finding.message ?? finding.title ?? "See plugin report.",
+    evidence: finding.evidence,
+  };
+}
+
+function findingFrequencyRows(entries) {
+  const byCode = new Map();
+  for (const entry of entries) {
+    const seenForPlugin = new Set();
+    for (const finding of entry.findings) {
+      const current = byCode.get(finding.code) ?? {
+        code: finding.code,
+        count: 0,
+        plugins: 0,
+        errors: 0,
+        warnings: 0,
+      };
+      current.count += 1;
+      if (!seenForPlugin.has(finding.code)) {
+        current.plugins += 1;
+        seenForPlugin.add(finding.code);
+      }
+      if (finding.kind === "error") current.errors += 1;
+      else current.warnings += 1;
+      byCode.set(finding.code, current);
+    }
+  }
+  return [...byCode.values()].sort((a, b) => b.plugins - a.plugins || b.count - a.count);
+}
+
+function renderBatchMarkdown(report) {
+  return [
+    "# Plugin Inspector Batch Report",
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Root: ${report.rootDir}`,
+    "",
+    "## Summary",
+    "",
+    renderMarkdownTable(
+      [
+        ["Plugins", report.summary.pluginCount],
+        ["Passed", report.summary.passed],
+        ["Failed", report.summary.failed],
+        ["Plugins with errors", report.summary.pluginsWithErrors],
+        ["Plugins with warnings", report.summary.pluginsWithWarnings],
+        ["Errors", report.summary.errorCount],
+        ["Warnings", report.summary.warningCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Finding Frequency",
+    "",
+    report.findingFrequency.length
+      ? renderMarkdownTable(
+          report.findingFrequency.map((row) => [
+            row.code,
+            row.plugins,
+            row.count,
+            row.errors,
+            row.warnings,
+          ]),
+          ["Code", "Plugins", "Findings", "Errors", "Warnings"],
+        )
+      : "_No findings._",
+    "",
+    "## Plugins",
+    "",
+    report.plugins.length
+      ? renderMarkdownTable(
+          report.plugins.map((plugin) => [
+            plugin.packageName,
+            plugin.relativePath,
+            plugin.status,
+            plugin.errorCount,
+            plugin.warningCount,
+          ]),
+          ["Package", "Path", "Status", "Errors", "Warnings"],
+        )
+      : "_No plugin roots discovered._",
+  ].join("\n");
+}
+
+async function runWithConcurrency(items, concurrency, worker) {
+  let index = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (index < items.length) {
+      const item = items[index];
+      index += 1;
+      await worker(item);
+    }
+  });
+  await Promise.all(runners);
+}
+
+async function isPluginRoot(dir) {
+  if (existsSync(path.join(dir, "plugin-inspector.config.json"))) return true;
+  if (existsSync(path.join(dir, ".plugin-inspector.json"))) return true;
+  if (existsSync(path.join(dir, "openclaw.plugin.json"))) return true;
+  const packageJsonPath = path.join(dir, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return Boolean(packageJson.openclaw || packageJson.pluginInspector || packageJson["plugin-inspector"]);
+  } catch {
+    return false;
+  }
+}
+
+function packageNameFromReport(report) {
+  return (
+    report.fixtures?.[0]?.package?.packageJson?.name ??
+    report.fixtures?.[0]?.package?.name ??
+    report.fixtures?.[0]?.name ??
+    report.fixtures?.[0]?.id ??
+    "plugin"
+  );
+}
+
+function slugForPath(value) {
+  return (
+    String(value)
+      .replaceAll(path.sep, "-")
+      .replace(/[^a-zA-Z0-9._-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "plugin"
+  );
+}

package/src/cli.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import {
   loadPluginConfig,
   renderTextSummary,
+  runBatchAnalysis,
   sanitizeReportArtifact,
   runPluginCheck,
 } from "./index.js";
@@ -43,6 +44,8 @@ try {
     }
   } else if (command === "ci") {
     await runCi(commandArgs);
+  } else if (command === "batch") {
+    await runBatch(commandArgs);
   } else if (command === "capture") {
     await runCapture(commandArgs);
   } else {
@@ -53,6 +56,38 @@ try {
   process.exitCode = 1;
 }
 
+async function runBatch(commandArgs) {
+  const inputDir = readFirstPositional(commandArgs, new Set(["--out", "--openclaw", "--concurrency"]));
+  const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const concurrency = Number(readFlag(commandArgs, "--concurrency") ?? "4");
+  const json = commandArgs.includes("--json");
+  const check = commandArgs.includes("--check");
+  const keepPluginReports = commandArgs.includes("--keep-plugin-reports");
+  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  if (!inputDir) {
+    throw new Error("batch requires a folder of plugin roots");
+  }
+  const { report, paths } = await runBatchAnalysis({
+    rootDir: inputDir,
+    outDir,
+    openclawPath,
+    concurrency,
+    includeInspectorGaps,
+    keepPluginReports,
+  });
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderBatchTextSummary(report, paths));
+  }
+
+  if (check && report.summary.pluginsWithErrors > 0) {
+    throw new Error(`plugin-inspector batch found ${report.summary.pluginsWithErrors} plugin(s) with errors`);
+  }
+}
+
 async function runConfig(commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
@@ -75,10 +110,12 @@ async function runCheck(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs);
+  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
   const { report, paths } = await runPluginCheck({
     allowExecution,
     capture,
     configPath,
+    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -164,10 +201,12 @@ async function runCi(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs, { defaultEnabled: true });
+  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
   const { report, reportDir } = await runCiCompatibilityReport({
     allowExecution,
     capture,
     configPath,
+    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -204,10 +243,19 @@ async function runCi(commandArgs) {
   }
 }
 
-async function runCiCompatibilityReport({ allowExecution, capture, configPath, mockSdk, openclawPath, outDir, pluginRoot }) {
+async function runCiCompatibilityReport({
+  allowExecution,
+  capture,
+  configPath,
+  includeInspectorGaps,
+  mockSdk,
+  openclawPath,
+  outDir,
+  pluginRoot,
+}) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
-    const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
+    const report = await inspectCompatibilityFixtureSet(config, { includeInspectorGaps, openclawPath });
     await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
     return {
       report,
@@ -215,7 +263,15 @@ async function runCiCompatibilityReport({ allowExecution, capture, configPath, m
     };
   }
 
-  const { report } = await runPluginCheck({ allowExecution, capture, mockSdk, openclawPath, outDir, pluginRoot });
+  const { report } = await runPluginCheck({
+    allowExecution,
+    capture,
+    includeInspectorGaps,
+    mockSdk,
+    openclawPath,
+    outDir,
+    pluginRoot,
+  });
   return {
     report,
     reportDir: path.resolve(pluginRoot ?? process.cwd(), outDir),
@@ -326,6 +382,34 @@ function renderCiTextSummary(summary) {
   ].join("\n");
 }
 
+function renderBatchTextSummary(report, paths) {
+  const lines = [
+    "Plugin Inspector Batch",
+    `Plugins: ${report.summary.pluginCount}`,
+    `Plugins with errors: ${report.summary.pluginsWithErrors}`,
+    `Plugins with warnings: ${report.summary.pluginsWithWarnings}`,
+    `Finding codes: ${report.summary.findingCodeCount}`,
+    "",
+    "Reports:",
+    `- JSON: ${paths.jsonPath}`,
+    `- Markdown: ${paths.markdownPath}`,
+  ];
+  const topFinding = report.findingFrequency[0];
+  if (topFinding) {
+    lines.push("", `Top finding: ${topFinding.code} (${topFinding.plugins} plugin(s))`);
+  }
+  return lines.join("\n");
+}
+
+function readFirstPositional(args, valueFlags = new Set()) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("-")) return arg;
+    if (valueFlags.has(arg)) index += 1;
+  }
+  return undefined;
+}
+
 function initCommandSummary(result) {
   return {
     dryRun: result.dryRun,
@@ -353,16 +437,18 @@ 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] [--json]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--include-inspector-gaps] [--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>] [--check] [--json]
+  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--include-inspector-gaps] [--check] [--json]
   plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--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] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--include-inspector-gaps] [--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.
 CI writes SARIF and JUnit artifacts by default; check/inspect can write them with --sarif and --junit.
 Runtime capture is opt-in because it imports plugin code; use --runtime with --allow-execute or PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
+Inspector coverage gaps are hidden by default; pass --include-inspector-gaps for maintainer coverage reports.
 `);
 }

package/src/index.js

@@ -17,6 +17,7 @@ import * as runtimeReconciliationApi from "./runtime-reconciliation.js";
 import * as syntheticEntrypointApi from "./synthetic-entrypoint.js";
 import * as syntheticProbeSuiteApi from "./synthetic-probe-suite.js";
 import * as syntheticProbesApi from "./synthetic-probes.js";
+import * as batchApi from "./batch.js";
 
 export const pluginRoot = Object.freeze({
   loadConfig: pluginApi.loadPluginConfig,
@@ -26,6 +27,12 @@ export const pluginRoot = Object.freeze({
   setup: pluginApi.setupPluginInspector,
 });
 
+export const batch = Object.freeze({
+  discoverPluginRoots: batchApi.discoverPluginRoots,
+  run: batchApi.runBatchAnalysis,
+  writeReport: batchApi.writeBatchReport,
+});
+
 export const fixtureSuites = Object.freeze({
   loadConfig: configApi.loadInspectorConfig,
   inspect: pluginApi.inspectCompatibilityFixtureSetConfig,
@@ -131,6 +138,11 @@ export const synthetic = Object.freeze({
   defaultRegistrationArguments: syntheticProbesApi.defaultSyntheticRegistrationArguments,
 });
 
+export {
+  discoverPluginRoots,
+  runBatchAnalysis,
+  writeBatchReport,
+} from "./batch.js";
 export {
   capturePluginEntrypoint,
   buildFixtureSetColdImportReadiness,

package/src/inspector.js

@@ -37,6 +37,7 @@ export async function inspectCompatibilityFixtureSet(config, options = {}) {
     failures,
     generatedAt: options.generatedAt,
     executionResults: options.executionResults,
+    includeInspectorGaps: options.includeInspectorGaps,
     targetOpenClaw,
     buildFixtureReport: ({ fixture, inspection }) =>
       buildCompatibilityFixtureReport({

package/src/issues.js

@@ -333,6 +333,10 @@ export function classifyIssueFinding(finding, targetOpenClaw, metadata = {}) {
   };
 }
 
+export function isInspectorGapFinding(finding, targetOpenClaw) {
+  return issueMetadata(finding, targetOpenClaw).issueClass === "inspector-gap";
+}
+
 export function summarizeIssueClasses(issues) {
   const summary = {
     "compat-gap": 0,

package/src/report.js

@@ -3,7 +3,7 @@ import { renderMarkdownTable, writeArtifacts, writeJsonMarkdownArtifacts } from
 import { renderCompatibilityIssuesReport, renderCompatibilityMarkdownReport } from "./compatibility-report.js";
 import { buildContractProbes } from "./contract-probes.js";
 import { classifyCompatibilityFixture } from "./fixture-summary.js";
-import { buildIssues, summarizeIssueClasses } from "./issues.js";
+import { buildIssues, isInspectorGapFinding, summarizeIssueClasses } from "./issues.js";
 import { sanitizeReportArtifact } from "./report-sanitizer.js";
 import { applyRuntimeExecutionCoverage } from "./runtime-reconciliation.js";
 
@@ -141,18 +141,24 @@ export async function buildCompatibilityReport(options = {}) {
     decisions,
   });
 
+  const visibleWarnings = filterVisibleFindings(warnings, targetOpenClaw, options);
+  const visibleSuggestions = filterVisibleFindings(suggestions, targetOpenClaw, options);
   const runtimeCoverage = applyRuntimeExecutionCoverage({
-    findings: [...warnings, ...suggestions],
+    findings: [...visibleWarnings, ...visibleSuggestions],
     executionResults: options.executionResults,
   });
   const issues = buildIssues({
     breakages,
-    warnings,
-    suggestions,
+    warnings: visibleWarnings,
+    suggestions: visibleSuggestions,
     targetOpenClaw,
     idPrefix: options.issueIdPrefix,
   });
-  const contractProbes = buildContractProbes({ warnings, suggestions, fixtures: fixtureReports });
+  const contractProbes = buildContractProbes({
+    warnings: visibleWarnings,
+    suggestions: visibleSuggestions,
+    fixtures: fixtureReports,
+  });
   const issueSummary = summarizeIssueClasses(issues);
   const openIssues = issues.filter((issue) => issue.status !== "runtime-covered");
   const openIssueSummary = summarizeIssueClasses(openIssues);
@@ -165,8 +171,8 @@ export async function buildCompatibilityReport(options = {}) {
       fixtureCount: fixtureReports.length,
       highPriorityFixtures: fixtureReports.filter((fixture) => fixture.priority === "high").length,
       breakageCount: breakages.length,
-      warningCount: warnings.length,
-      suggestionCount: suggestions.length,
+      warningCount: visibleWarnings.length,
+      suggestionCount: visibleSuggestions.length,
       decisionCount: decisions.length,
       logCount: logs.length,
       issueCount: issues.length,
@@ -190,8 +196,8 @@ export async function buildCompatibilityReport(options = {}) {
     },
     fixtures: fixtureReports,
     breakages,
-    warnings,
-    suggestions,
+    warnings: visibleWarnings,
+    suggestions: visibleSuggestions,
     issues,
     contractProbes,
     logs,
@@ -199,6 +205,13 @@ export async function buildCompatibilityReport(options = {}) {
   };
 }
 
+function filterVisibleFindings(findings, targetOpenClaw, options) {
+  if (options.includeInspectorGaps === true) {
+    return findings;
+  }
+  return findings.filter((finding) => !isInspectorGapFinding(finding, targetOpenClaw));
+}
+
 export function classifyCompatRecordCoverage({ targetOpenClaw, findings, suggestions, logs, decisions }) {
   if (targetOpenClaw.status !== "ok") {
     logs.push({

package/src/sdk-mock.js

@@ -671,6 +671,24 @@ function resolveExistingSourcePath(target) {
 ` : ""}
 function createMockValue(name) {
   function fn(...args) {
+    if (name === "resolveDefaultAgentDir") {
+      return mockAgentDir();
+    }
+    if (name === "resolveAgentDir") {
+      return mockAgentDir(args[1]);
+    }
+    if (name === "resolveUserPath") {
+      return typeof args[0] === "string" ? args[0] : mockAgentDir();
+    }
+    if (name === "resolveAuthProfileOrder") {
+      return [];
+    }
+    if (name === "resolveWindowsSpawnProgram") {
+      return mockWindowsSpawnProgram(args[0]);
+    }
+    if (name === "materializeWindowsSpawnProgram") {
+      return mockWindowsSpawnInvocation(args[0], args[1]);
+    }
     if (name === "resolvePreferredOpenClawTmpDir") {
       return process.env.TMPDIR || "/tmp";
     }
@@ -707,6 +725,80 @@ function createMockValue(name) {
   });
 }
 
+function mockAgentDir(agentId = "main") {
+  const base = process.env.TMPDIR || process.env.TEMP || process.env.TMP || "/tmp";
+  const safeAgentId = String(agentId || "main").replace(/[^a-zA-Z0-9._-]/g, "-");
+  return base.replace(/[\\/]+$/, "") + "/plugin-inspector-openclaw/agents/" + safeAgentId + "/agent";
+}
+
+function mockWindowsSpawnProgram(params = {}) {
+  return {
+    command: typeof params.command === "string" && params.command.trim() ? params.command : process.execPath,
+    leadingArgv: [],
+    resolution: "mock",
+    packageName: typeof params.packageName === "string" ? params.packageName : undefined,
+  };
+}
+
+function mockWindowsSpawnInvocation(program = {}, argv = []) {
+  const command = typeof program.command === "string" && program.command.trim() ? program.command : process.execPath;
+  if (program.packageName === "@openai/codex") {
+    return {
+      command: process.execPath,
+      argv: ["-e", mockCodexAppServerScript()],
+      resolution: program.resolution ?? "mock",
+      windowsHide: true,
+    };
+  }
+  return {
+    command,
+    argv: [...(Array.isArray(program.leadingArgv) ? program.leadingArgv : []), ...(Array.isArray(argv) ? argv : [])],
+    resolution: program.resolution ?? "mock",
+    shell: program.shell,
+    windowsHide: program.windowsHide,
+  };
+}
+
+function mockCodexAppServerScript() {
+  return [
+    "const readline = require('node:readline');",
+    "const rl = readline.createInterface({ input: process.stdin });",
+    "let idleTimer;",
+    "function scheduleIdleExit() {",
+    "  if (idleTimer) clearTimeout(idleTimer);",
+    "  idleTimer = setTimeout(() => process.exit(0), 1000);",
+    "}",
+    "function write(id, result) { process.stdout.write(JSON.stringify({ id, result }) + String.fromCharCode(10)); }",
+    "rl.on('line', (line) => {",
+    "  let message;",
+    "  try { message = JSON.parse(line); } catch { return; }",
+    "  if (message.id === undefined || message.id === null) return;",
+    "  switch (message.method) {",
+    "    case 'initialize':",
+    "      write(message.id, { userAgent: 'openclaw/999.0.0 (plugin-inspector mock)' });",
+    "      break;",
+    "    case 'model/list':",
+    "      write(message.id, { data: [] });",
+    "      break;",
+    "    case 'thread/list':",
+    "    case 'mcpServerStatus/list':",
+    "    case 'skills/list':",
+    "      write(message.id, { data: [] });",
+    "      break;",
+    "    case 'account/read':",
+    "      write(message.id, null);",
+    "      break;",
+    "    case 'account/rateLimits/read':",
+    "      write(message.id, null);",
+    "      break;",
+    "    default:",
+    "      process.stdout.write(JSON.stringify({ id: message.id, error: { code: -32601, message: 'mock method not implemented' } }) + String.fromCharCode(10));",
+    "  }",
+    "  scheduleIdleExit();",
+    "});",
+  ].join("\\n");
+}
+
 function createZNamespace() {
   const namespace = {
     any: () => createSchema(),