@openclaw/plugin-inspector 0.3.24 → 0.3.26

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 0.3.26 - 2026-09-20
+
+### Fixed
+
+- Recognize OpenClaw's declared private-local Plugin SDK subpaths and reserved bundled-plugin imports when inspecting bundled `extensions/*` fixtures, while continuing to report those imports for external plugins and genuinely missing SDK aliases.
+- Treat active OpenClaw conversation-access compat records with present contract tests as target-owned proof instead of repeatedly emitting a P1 Inspector probe backlog advisory.
+- Record explicit method-scoped Gateway probe prerequisites before calling handlers that require unavailable host state or live credentials; preserve actual response failures for admitted probes.
+- Preserve absent optional strings in SDK mocks and supply a stable runtime config snapshot to Gateway probes instead of inventing configured values or missing host accessors.
+- Generate SDK mocks for literal dynamic imports in retained handlers, including their named exports, while excluding TypeScript import types and keeping source inspection aligned with runtime capture.
+- Honor the OpenClaw lazy-runtime SDK contract in generated mocks, preserving deferred module loading, shared promise caches, explicit cache clearing, and rejected imports instead of returning callable placeholders.
+- Reject invalid batch concurrency instead of reporting success without inspecting any plugins, and preserve relative plugin paths in retained reports so similar directory names cannot overwrite each other's results.
+- Preserve error messages from the OpenClaw `error-runtime` SDK subpath in synthetic probes, including lazy CommonJS imports, so Gateway rejections report their actual cause and remain failures.
+- Keep tool-hook and conversation-privacy contract gaps open when runtime artifacts only capture hook registration. Preserve registration coverage and semantic contract probes.
+- Read OpenClaw compatibility records from the explicitly imported `registry-records.ts` data module, avoiding false missing-record findings after the registry split. Preserve inline registries and report missing delegated data as an error.
+
+## 0.3.25 - 2026-09-09
+
+### Fixed
+
+- Invoke each synthetic Gateway method once, including registrations with options, and validate its first emitted response's JSON wire representation instead of treating any nonthrowing callback as successful. Preserve explicit response authority, returned-payload fallback, deferred replies within the existing deadline, and accepted-only initial responses.
+- Bound synthetic callback waits and cancellation, stop dependent probes after a timeout, and supervise CLI capture plus retained callbacks in one child. Validate report shape and counts before delivery while preserving complete failed-row reports, bounded plugin output, and in-process callback identity. Thanks @SebTardif.
+- Run `registerService` start, stop, and dispose probes serially so teardown cannot overlap startup.
+- Bound real-SDK CLI capture in an owned child, including stalled imports, busy registration, and retained timers. Give in-process capture a finite 30-second default deadline while preserving caller runtime and handler identity; arbitrary in-process JavaScript cannot be forcibly canceled. Thanks @SebTardif.
+- Capture and synthetically probe compiled CommonJS plugins with generated SDK mocks, including lazy `require()` calls, and discover their SDK source references. CommonJS mocking requires Node.js 22.15+ synchronous module hooks; the package engine and existing ESM/TypeScript capture remain unchanged.
+- Bound mock-SDK capture and profile child lifetimes, output, and process sampling; clean owned POSIX descendants through stdio close and keep timeout/cancellation outcomes unsuccessful. Flush complete capture JSON before exiting despite retained plugin timers. Thanks @SebTardif.
+- Profile the default import-loop capture runner directly so its timeout also owns plugin execution. Validate fresh, bounded capture artifacts; RSS/CPU and wall-time measurements now exclude the intermediate CLI wrapper and are not directly comparable with historical profiles.
+- Bound OpenClaw npm metadata and tarball downloads with a deadline through response-body reads, reject oversized responses, and release failed downloads. Resolve `latest` and `beta` through the small npm dist-tags endpoint before fetching exact-version metadata, keeping the 16 MiB metadata limit usable.
+- Capture plugins that bind `api.runtime.modelAuth` during registration with credential-free defaults; auth acquisition remains an explicit synthetic failure.
+- Report absent build output and missing entrypoints before SDK alias blockers in cold-import readiness, preserving build-required totals and all remediation evidence.
+- Recognize board widget content kinds, memory prompt preparation, transcript source providers, worker providers, and MCP server connection resolvers as metadata-only synthetic probes without invoking runtime callbacks.
+
 ## 0.3.24 - 2026-08-31
 
 ### Fixed

package/README.md

@@ -200,6 +200,13 @@ Common options:
 | `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
 | `--no-sarif` / `--no-junit` | Disable default `ci` outputs. |
 
+For `batch`, `--concurrency <n>` must be a finite number (default `4`, rounded
+and clamped to `1`–`32` workers). Invalid or missing values fail before inspection
+or report writes. `--keep-plugin-reports` retains individual reports under
+`<out>/plugins/<relative-plugin-path>/`, preserving the corpus directory layout
+and names so plugins such as `a/b`, `a-b`, and `a b` cannot overwrite each other's
+reports. If the corpus root is itself a plugin, its reports go in `<out>/plugins/`.
+
 Run the built-in help for the exact CLI surface:
 
 ```bash
@@ -232,6 +239,20 @@ That keeps compatibility CI offline and credential-free. It does not call live
 services, launch OpenClaw, run provider SDKs, or emulate service lifecycle side
 effects.
 
+CommonJS SDK mocking, including compiled `.cjs` entrypoints and lazy `require()`
+calls in synthetic handlers, requires Node.js 22.15 or newer with
+`module.registerHooks()`. On older Node versions, upgrade Node.js or use an
+ESM/TypeScript entrypoint. This capability requirement does not change the
+package's Node.js `>=22` engine range or gate existing ESM/TypeScript capture.
+Static inspection also discovers literal CommonJS SDK `require()` references.
+
+The default capture `api.runtime.modelAuth` passes synthetic provider IDs through
+unchanged, returns fresh empty auth stores and profile lists, and reports no
+configured API keys. Auth acquisition rejects with a mock-auth-unavailable error;
+it never looks up host credentials. This supports registration and no-auth
+callbacks, not provider alias validation or authenticated execution. An explicitly
+supplied runtime is preserved unchanged, including an empty runtime.
+
 Synthetic probes classify widget presenters as metadata-only. They record the
 registration without calling its match, availability, or presentation callbacks,
 including when channel, provider, or lifecycle execution is enabled.
@@ -239,6 +260,20 @@ including when channel, provider, or lifecycle execution is enabled.
 Use `--real-sdk` only when the plugin workspace already has real SDK
 dependencies installed and you intentionally want that path.
 
+Real-SDK CLI capture runs in an owned child, including runtime capture enabled
+by flags or plugin config. The parent bounds imports and registration, then
+cleans up retained plugin timers after the child flushes its complete result.
+It uses installed SDK dependencies without loading the mock SDK.
+
+The real-SDK programmatic API stays in-process to preserve supplied runtime
+objects and retained handler identity. Its 30-second default deadline reports
+`capture-timeout`, stops later inspector-owned phases, and aborts supported
+setup reads. Caller `signal` cancellation also stops later phases. Neither
+mechanism can preempt a synchronous JavaScript loop, unload an import, stop
+arbitrary plugin side effects, or clear plugin-owned timers in the caller's
+process. Only owned-child capture provides that process-lifetime boundary.
+Override the API budget with `timeoutMs` or `PLUGIN_INSPECTOR_CAPTURE_TIMEOUT_MS`.
+
 Runtime capture writes:
 
 - `reports/plugin-inspector-runtime-capture.json`
@@ -250,6 +285,110 @@ Capture one entrypoint directly:
 plugin-inspector capture ./dist/index.js --mock-sdk --allow-execute
 ```
 
+CLI capture, mock-SDK API capture, and import-loop/runtime profiles give each
+child a 30-second budget. Capture reports `capture-timeout`; timed-out profile samples
+always have a nonzero `exitCode`, even if a SIGTERM handler exits zero.
+Pass an `AbortSignal` as `signal` to cancel owned-child work. Cancellation is
+never a successful capture or profile sample.
+
+On POSIX, each child owns a separate process group. Completion waits for
+stdout/stderr to close and cleans descendants, including after a successful
+leader exit. Shutdown sends SIGTERM, then SIGKILL after a 1-second grace
+period. A further 1-second close deadline fails the operation if pipes remain
+open. Descendants that deliberately leave the group are not contained;
+this is lifecycle supervision, not a sandbox. Windows retains direct-child
+termination and the bounded close deadline, not POSIX group cleanup.
+
+The API options `timeoutMs`, `killGraceMs`, and `maxOutputBytes` take precedence
+over `PLUGIN_INSPECTOR_CAPTURE_TIMEOUT_MS`, `PLUGIN_INSPECTOR_CAPTURE_KILL_GRACE_MS`,
+and `PLUGIN_INSPECTOR_CAPTURE_MAX_OUTPUT_BYTES` for owned-child capture. Profiles use
+the corresponding `PLUGIN_INSPECTOR_PROFILE_*` variables. Values must be finite
+positive numbers (zero does not disable limits); invalid values fall through
+to the environment, then defaults. Durations/byte limits cannot exceed
+2,147,483,647; grace cannot exceed 30,000 ms.
+
+Each profiled stdout/stderr stream retains at most 1 MiB by default while
+continuing to drain output. Owned-child capture retains at most 10 MiB per pipe and
+fails if its JSON response is truncated; intercepted plugin stdout/stderr
+inside that response retains at most 1 MiB each. The optional `ps` sampler
+also has bounded output, execution, and cleanup.
+
+Default import-loop profiles launch the mock capture runner directly under one
+profile budget, for both baseline and plugin samples. Their JSON artifacts
+retain capture's 10 MiB default limit (`PLUGIN_INSPECTOR_CAPTURE_MAX_OUTPUT_BYTES`,
+or an explicit `maxOutputBytes` override), separately from the profile's
+1 MiB stdout/stderr limits. Artifacts are accepted only after a successful
+current capture. RSS and CPU now measure the actual runner, and wall time no
+longer includes intermediate CLI startup. Historical measurements from the
+CLI-wrapper route are not directly comparable. Custom `captureCommand` and
+`captureScript` launch contracts are unchanged; custom detached groups are
+outside the owned process group.
+
+These limits apply to owned child processes only. The public in-process
+`captureEntrypoint` path preserves retained handler identity and does not
+claim to cancel synchronous plugin code or retained callbacks.
+
+Synthetic probe APIs give each invoked callback a 30-second default budget.
+Set `timeoutMs` or `PLUGIN_INSPECTOR_PROBE_TIMEOUT_MS`; the same finite positive
+API-then-environment validation applies, with no zero or infinite opt-out.
+A timed-out callback becomes a failed row and remaining dependent probes are
+blocked. Ordinary handler failures remain failed rows without stopping
+independent probes. Caller `signal` cancellation rejects the API call.
+Timeout and cancellation abort supported handler signal arguments and observe
+late promise settlement, but cannot preempt synchronous JavaScript or arbitrary
+plugin side effects. Programmatic probes stay in-process and preserve caller
+runtime objects and retained callback identity.
+
+Gateway method probes invoke each registered handler once, including positional
+`(method, handler, options)` registrations; captured `handler`/`run`/`execute`
+aliases do not create extra calls. The handler receives synthetic Gateway
+options and a void `respond(ok, payload, error, meta)` callback. Existing
+`registrationProbeInputs` overrides remain available.
+
+For a method that needs unavailable host state or live credentials, pass
+`gatewayMethodPrerequisites: { "fixture.account": "saved account required" }`
+to `runCapturedSyntheticProbes` or `runEntrypointSyntheticProbes`. The named
+method produces a `blocked` row with its method and reason before its handler
+runs. Other methods retain normal response validation. Once a caller supplies
+the required inputs and runtime, omit that method from the prerequisite map;
+rejected or malformed responses still fail. This option never reports a
+missing prerequisite as a passing runtime check.
+
+The first emitted response is authoritative, even when malformed. Probes check
+its JSON-serialized response/error shape: `ok: true` passes, `ok: false` fails,
+and later responses cannot overwrite the outcome. Logging `meta` is not a wire
+field. Without an explicit response, a non-`undefined` return is adapted into a
+successful payload, including `false`, `null`, and `{ ok: false }`, matching the
+OpenClaw plugin registrar. A void handler can respond later within the existing
+probe deadline; no response or return before that deadline fails. Handler throws,
+rejections, and timeouts still fail under the ordinary probe rules.
+
+This observes the initial RPC response plus ordinary handler settlement within
+the existing deadline. It does not prove asynchronous operation completion,
+transport delivery, or authorization. An accepted-only success is valid once the
+handler settles; probes do not implicitly request `expectFinal` or reject legal
+multi-frame methods. No Gateway connection or live host call is made.
+
+`synthetic-probes-cli.js` runs capture and retained callbacks together in one
+owned child. Its whole-child budget also defaults to 30 seconds, including
+imports and registration, with `PLUGIN_INSPECTOR_PROBE_TIMEOUT_MS`,
+`PLUGIN_INSPECTOR_PROBE_KILL_GRACE_MS`, and
+`PLUGIN_INSPECTOR_PROBE_MAX_OUTPUT_BYTES` overrides. Shutdown uses the same
+bounded grace and process-group cleanup as capture. The default report and
+per-pipe limit is 10 MiB, matching capture; intercepted plugin stdout and stderr are each capped
+at 1 MiB and kept separate from the report protocol.
+
+Completed synthetic reports are still written even when they contain failed
+probe rows; the CLI exits successfully after delivering them, and CI policy
+evaluates those rows. Child timeout, cancellation, truncated output, or an
+oversized or malformed report instead exits unsuccessfully without writing a
+new output artifact. The CLI validates the report shape, row identities and
+statuses, and summary counts before publication; valid empty and blocked
+reports are preserved. This is protocol validation, not authenticated
+completion or a security sandbox: same-process plugin code can still fabricate
+a valid report. Healthy retained intervals cannot keep the child alive after
+its complete report is flushed.
+
 ## CI
 
 `plugin-inspector ci` writes the normal compatibility report plus CI-native
@@ -444,6 +583,8 @@ npm run check
 ```
 
 `npm run check` runs the Node test suite and the package-contents guard. The
+test runner limits parallel test files to four so process-supervision tests do
+not contend with a machine-wide burst of child processes for their deadlines. The
 contents guard shells through `npm pack --dry-run --json` and verifies the npm
 tarball includes package entrypoints, examples, README assets, and no private
 `test/`, `scripts/`, or `.github/` paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",
@@ -57,7 +57,7 @@
     "release:readiness": "npm run release:local && npm run release:crabpot",
     "release:local": "npm run check",
     "release:notes": "node scripts/release-notes.mjs --unreleased",
-    "test": "node --test test/*.test.js",
+    "test": "node --test --test-concurrency=4 test/*.test.js",
     "check:changed": "npm run check",
     "test:changed": "npm test",
     "crabbox:hydrate": "crabbox actions hydrate",
@@ -72,6 +72,8 @@
     "ci"
   ],
   "dependencies": {
+    "acorn": "^8.18.0",
+    "eslint-scope": "^8.4.0",
     "semver": "^7.8.5",
     "tar": "^7.5.22"
   }

package/src/api.js

@@ -226,6 +226,13 @@ export async function runPluginCheck(options = {}) {
       mockSdk,
       report,
       rootDir: config.rootDir,
+      isolateCapture: options.isolateCapture,
+      timeoutMs: options.timeoutMs,
+      killGraceMs: options.killGraceMs,
+      maxOutputBytes: options.maxOutputBytes,
+      signal: options.signal,
+      env: options.env,
+      apiOptions: options.apiOptions,
     });
     const runtimeCapturePaths = await writeRuntimeCaptureReport(runtimeCapture, {
       jsonPath: path.resolve(config.rootDir, outDir, "plugin-inspector-runtime-capture.json"),

package/src/artifacts.js

@@ -1,6 +1,27 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { mkdir, open, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+export async function readBoundedJsonArtifact(filePath, maxBytes) {
+  const file = await open(filePath, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile()) throw new Error("expected a regular result file");
+    if (stat.size > maxBytes) throw new Error("result exceeded its byte limit");
+    const chunks = [];
+    let bytes = 0;
+    // end is inclusive: read at most limit + 1 even if the file grew after stat.
+    for await (const chunk of file.createReadStream({ end: maxBytes, autoClose: false })) {
+      chunks.push(chunk);
+      bytes += chunk.length;
+    }
+    if (bytes > maxBytes) throw new Error("result exceeded its byte limit");
+    return JSON.parse(Buffer.concat(chunks, bytes).toString("utf8"));
+  } finally {
+    await file.close();
+  }
+}
+
 export async function writeArtifacts(artifacts, options = {}) {
   if (!Array.isArray(artifacts) || artifacts.length === 0) {
     throw new TypeError("writeArtifacts requires at least one artifact");

package/src/batch.js

@@ -21,7 +21,11 @@ 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 requestedConcurrency = options.concurrency ?? 4;
+  if (!Number.isFinite(requestedConcurrency)) {
+    throw new TypeError("batch concurrency must be a finite number");
+  }
+  const concurrency = Math.max(1, Math.min(Math.round(requestedConcurrency), 32));
   const keepPluginReports = options.keepPluginReports === true;
   const targetOpenClaw =
     options.targetOpenClaw ??
@@ -35,8 +39,8 @@ export async function runBatchAnalysis(options = {}) {
   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)));
+        ? path.join(outRoot, "plugins", path.relative(rootDir, pluginRoot))
+        : path.join(tempRoot, path.relative(rootDir, pluginRoot));
       entries.push(
         await inspectBatchPlugin(pluginRoot, {
           ...options,
@@ -306,12 +310,3 @@ function packageNameFromReport(report) {
     "plugin"
   );
 }
-
-function slugForPath(value) {
-  return (
-    String(value)
-      .replaceAll(path.sep, "-")
-      .replace(/[^a-zA-Z0-9._-]+/g, "-")
-      .replace(/^-+|-+$/g, "") || "plugin"
-  );
-}

package/src/capture-api.js

@@ -203,6 +203,17 @@ function createRuntimeContext(options) {
     logger: options.logger ?? console,
     now: () => new Date(0),
     tts: runtime.tts ?? {},
+    // Synthetic provider IDs pass through; capture never resolves host aliases or credentials.
+    modelAuth: {
+      resolveProviderIdForAuth: (provider) => provider,
+      ensureAuthProfileStore: () => ({ version: 1, profiles: {} }),
+      resolveAuthProfileOrder: () => [],
+      listProfilesForProvider: () => [],
+      isProviderApiKeyConfigured: () => false,
+      getApiKeyForModel: rejectCaptureModelAuth,
+      getRuntimeAuthForModel: rejectCaptureModelAuth,
+      resolveApiKeyForProvider: rejectCaptureModelAuth,
+    },
     state: {
       resolveStateDir: () => options.stateDir ?? process.cwd(),
       openBlobStore(storeOptions) {
@@ -228,6 +239,10 @@ function createRuntimeContext(options) {
   };
 }
 
+async function rejectCaptureModelAuth() {
+  throw new Error("Model auth is unavailable in capture mocks");
+}
+
 function createBlobStoreContext(options) {
   const values = new Map();
   const entryInfo = (key, entry) => ({

package/src/capture-cli.js

@@ -23,7 +23,7 @@ async function run(commandArgs) {
     throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
   }
 
-  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
+  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot, isolateCapture: true });
   const json = `${JSON.stringify(result, null, 2)}\n`;
   if (outputPath) {
     await writeArtifacts([{ path: outputPath, content: json }]);

package/src/capture-config.js

@@ -6,7 +6,7 @@ export async function captureApiOptionsForPlugin(apiOptions = {}, options = {})
     return apiOptions;
   }
 
-  const pluginConfig = await readSamplePluginConfig(options.pluginRoot);
+  const pluginConfig = await readSamplePluginConfig(options.pluginRoot, options.signal);
   if (pluginConfig === undefined) {
     return apiOptions;
   }
@@ -16,15 +16,16 @@ export async function captureApiOptionsForPlugin(apiOptions = {}, options = {})
   };
 }
 
-async function readSamplePluginConfig(pluginRoot) {
-  const manifestPath = await findNearestManifestPath(pluginRoot);
+async function readSamplePluginConfig(pluginRoot, signal) {
+  const manifestPath = await findNearestManifestPath(pluginRoot, signal);
   if (!manifestPath) {
     return undefined;
   }
   let manifest;
   try {
-    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    manifest = JSON.parse(await readFile(manifestPath, { encoding: "utf8", signal }));
   } catch {
+    signal?.throwIfAborted();
     return undefined;
   }
 
@@ -32,14 +33,16 @@ async function readSamplePluginConfig(pluginRoot) {
   return isPlainObject(sample) && Object.keys(sample).length > 0 ? sample : undefined;
 }
 
-async function findNearestManifestPath(pluginRoot) {
+async function findNearestManifestPath(pluginRoot, signal) {
   let current = path.resolve(pluginRoot);
   while (true) {
     const manifestPath = path.join(current, "openclaw.plugin.json");
     try {
-      await readFile(manifestPath, "utf8");
+      await readFile(manifestPath, { encoding: "utf8", signal });
       return manifestPath;
-    } catch {}
+    } catch {
+      signal?.throwIfAborted();
+    }
 
     const parent = path.dirname(current);
     if (parent === current) {

package/src/cli.js

@@ -61,7 +61,9 @@ async function runBatch(commandArgs) {
   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 concurrency = commandArgs.includes("--concurrency")
+    ? Number(readFlag(commandArgs, "--concurrency") ?? NaN)
+    : 4;
   const json = commandArgs.includes("--json");
   const check = commandArgs.includes("--check");
   const keepPluginReports = commandArgs.includes("--keep-plugin-reports");
@@ -115,6 +117,7 @@ async function runCheck(commandArgs, options = {}) {
   const ciOutputs = readCiOutputFlags(commandArgs);
   const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, paths } = await runPluginCheck({
+    isolateCapture: true,
     allowExecution,
     authorFacing,
     capture,
@@ -279,6 +282,7 @@ async function runCiCompatibilityReport({
   }
 
   const { report } = await runPluginCheck({
+    isolateCapture: true,
     allowExecution,
     authorFacing,
     capture,
@@ -307,7 +311,7 @@ async function runCapture(commandArgs) {
     throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 or --allow-execute in an isolated workspace");
   }
 
-  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
+  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot, isolateCapture: true });
   const json = `${JSON.stringify(result, null, 2)}\n`;
   if (outputPath) {
     await writeArtifacts([{ path: outputPath, content: json }]);

package/src/cold-import-readiness.js

@@ -226,15 +226,15 @@ function readinessStatus(blockers) {
   if (blockers.length === 0) {
     return "ready";
   }
-  if (blockers.some((blocker) => blocker.code === "sdk-alias-required")) {
-    return "sdk-alias-required";
-  }
   if (blockers.some((blocker) => blocker.code === "build-required")) {
     return "build-required";
   }
   if (blockers.some((blocker) => blocker.code === "missing-entrypoint")) {
     return "missing";
   }
+  if (blockers.some((blocker) => blocker.code === "sdk-alias-required")) {
+    return "sdk-alias-required";
+  }
   if (blockers.some((blocker) => blocker.code === "ts-loader-required")) {
     return "ts-loader-required";
   }

package/src/fixture-summary.js

@@ -550,14 +550,16 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
 
   const conversationHooks = inspection.hooks.filter((hook) => conversationAccessHooks.has(hook));
   const conversationHookDetails = inspection.hookDetails.filter((hook) => conversationAccessHooks.has(hook.name));
-  if (conversationHooks.length > 0) {
+  const conversationCompatRecord = compatRecordForIssueCode("conversation-access-hook");
+  const conversationContractCovered = hasActiveTargetContractTests(targetOpenClaw, conversationCompatRecord);
+  if (conversationHooks.length > 0 && !conversationContractCovered) {
     warnings.push({
       fixture: fixture.id,
       code: "conversation-access-hook",
       level: "warning",
       message: "fixture observes raw model or conversation content and needs privacy-boundary contract probes",
       evidence: detailEvidence(conversationHookDetails),
-      compatRecord: compatRecordForIssueCode("conversation-access-hook"),
+      compatRecord: conversationCompatRecord,
     });
     decisions.push({
       fixture: fixture.id,
@@ -713,6 +715,15 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   return { breakages, warnings, suggestions, logs, decisions };
 }
 
+function hasActiveTargetContractTests(targetOpenClaw, compatRecord) {
+  if (!compatRecord || !["active", "supported"].includes(targetOpenClaw.compatRecordStatuses?.[compatRecord])) {
+    return false;
+  }
+  const tests = targetOpenClaw.compatRecordTests?.[compatRecord] ?? [];
+  const missingTests = targetOpenClaw.compatRecordMissingTests?.[compatRecord] ?? [];
+  return tests.length > 0 && missingTests.length === 0;
+}
+
 function classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings, decisions }) {
   const grouped = new Map();
   for (const finding of fixtureReport.sdkDeprecations ?? inspection.sdkDeprecations ?? []) {
@@ -883,10 +894,22 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
   }
 
   const sdkExports = new Set(targetOpenClaw.sdkExports);
-  const unknownImports = fixtureReport.sdkImportDetails.filter((sdkImport) => !sdkExports.has(sdkImport.specifier));
+  const bundledPluginId = bundledOpenClawPluginId(fixture, targetOpenClaw);
+  const isBundledFixture = bundledPluginId !== null;
+  const privateLocalSdkExports = new Set(targetOpenClaw.privateLocalSdkExports ?? []);
+  const unknownImports = fixtureReport.sdkImportDetails.filter(
+    (sdkImport) =>
+      !sdkExports.has(sdkImport.specifier) &&
+      !(isBundledFixture && privateLocalSdkExports.has(sdkImport.specifier)),
+  );
   const reservedSdkExports = new Set(targetOpenClaw.reservedSdkExports ?? []);
-  const reservedImports = fixtureReport.sdkImportDetails.filter((sdkImport) =>
-    reservedSdkExports.has(sdkImport.specifier),
+  const reservedImports = fixtureReport.sdkImportDetails.filter(
+    (sdkImport) =>
+      reservedSdkExports.has(sdkImport.specifier) &&
+      !(
+        bundledPluginId !== null &&
+        targetOpenClaw.reservedSdkExportOwners?.[sdkImport.specifier] === bundledPluginId
+      ),
   );
 
   if (reservedImports.length === 0 && unknownImports.length === 0) {
@@ -894,7 +917,9 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
       fixture: fixture.id,
       code: "sdk-exports-present",
       level: "log",
-      message: "all observed plugin SDK imports exist in target OpenClaw package exports",
+      message: isBundledFixture
+        ? "all observed plugin SDK imports are exported or declared private-local for bundled plugins"
+        : "all observed plugin SDK imports exist in target OpenClaw package exports",
       evidence: fixtureReport.sdkImports,
     });
     return;
@@ -938,6 +963,18 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
   }
 }
 
+function bundledOpenClawPluginId(fixture, targetOpenClaw) {
+  if (fixture.repo !== "local" || !fixture.checkoutPath || !targetOpenClaw.checkoutPath) return null;
+  const fixturePath = normalizeRepoPath(fixture.checkoutPath);
+  const targetPath = normalizeRepoPath(targetOpenClaw.checkoutPath);
+  const relativePath = targetPath === "."
+    ? fixturePath
+    : fixturePath.startsWith(`${targetPath}/`)
+      ? fixturePath.slice(targetPath.length + 1)
+      : "";
+  return relativePath.match(/^extensions\/([^/]+)(?:\/|$)/)?.[1] ?? null;
+}
+
 function addVersionDerivedFinding({ finding, fixtureReport, targetOpenClaw, breakages, warnings, suggestions }) {
   const compatibility = targetCompatibility(fixtureReport, targetOpenClaw);
   if (!compatibility) {