fix(update): classify unreadable plugin manifests (#110200)

VACInc · web-flow · commit 748fc044192a · 2026-07-17T16:33:04.000-07:00
Co-authored-by: VACInc &lt;3279061+VACInc@users.noreply.github.com&gt;
diff --git a/src/cli/update-cli/plugin-payload-validation.test.ts b/src/cli/update-cli/plugin-payload-validation.test.ts
@@ -2,7 +2,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { PluginInstallRecord } from "../../config/types.plugins.js";
 import { resolveOpenClawPackageRootSync } from "../../infra/openclaw-root.js";
 import { runPluginPayloadSmokeCheck } from "./plugin-payload-validation.js";
@@ -19,6 +19,7 @@ describe("runPluginPayloadSmokeCheck", () => {
     tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-payload-smoke-"));
   });
   afterEach(async () => {
+    vi.restoreAllMocks();
     await fs.rm(tmpRoot, { recursive: true, force: true });
   });
 
@@ -619,6 +620,32 @@ describe("runPluginPayloadSmokeCheck", () => {
     ]);
   });
 
+  it.each(["EACCES", "EPERM", "EIO"])(
+    "classifies a %s package.json read failure as unreadable",
+    async (code) => {
+      const dir = path.join(tmpRoot, "unreadable");
+      const packageJsonPath = path.join(dir, "package.json");
+      await writePackage(dir, { name: "unreadable" });
+      vi.spyOn(fs, "readFile").mockRejectedValueOnce(
+        Object.assign(new Error(`${code}: could not read ${packageJsonPath}`), { code }),
+      );
+
+      const result = await runPluginPayloadSmokeCheck({
+        records: { unreadable: { source: "npm", installPath: dir } },
+        env: {},
+      });
+
+      expect(result.failures).toStrictEqual([
+        {
+          pluginId: "unreadable",
+          installPath: dir,
+          reason: "unreadable-package-json",
+          detail: `Could not read package.json at ${packageJsonPath}: ${code}: could not read ${packageJsonPath}`,
+        },
+      ]);
+    },
+  );
+
   it("reports a failure when an install record is missing installPath", async () => {
     const result = await runPluginPayloadSmokeCheck({
       records: {
diff --git a/src/cli/update-cli/plugin-payload-validation.ts b/src/cli/update-cli/plugin-payload-validation.ts
@@ -13,6 +13,7 @@ type PluginPayloadSmokeFailureReason =
   | "missing-install-path"
   | "missing-package-dir"
   | "missing-package-json"
+  | "unreadable-package-json"
   | "invalid-package-json"
   | "missing-bundle-manifest"
   | "invalid-bundle-manifest"
@@ -121,6 +122,7 @@ type PackagePayloadManifest = PackageManifest & { main?: unknown; exports?: unkn
 
 type PackagePayloadManifestReadResult =
   | { status: "missing" }
+  | { status: "unreadable"; error: string }
   | { status: "invalid"; error: string }
   | { status: "present"; manifest: PackagePayloadManifest };
 
@@ -132,10 +134,16 @@ async function readPackagePayloadManifest(
   if (!packageJsonStat?.isFile()) {
     return { status: "missing" };
   }
+  let packageJson: string;
+  try {
+    packageJson = await fs.readFile(packageJsonPath, "utf8");
+  } catch (err) {
+    return { status: "unreadable", error: err instanceof Error ? err.message : String(err) };
+  }
   try {
     return {
       status: "present",
-      manifest: JSON.parse(await fs.readFile(packageJsonPath, "utf8")) as PackagePayloadManifest,
+      manifest: JSON.parse(packageJson) as PackagePayloadManifest,
     };
   } catch (err) {
     return { status: "invalid", error: err instanceof Error ? err.message : String(err) };
@@ -147,6 +155,15 @@ function formatPackagePayloadReadFailure(params: {
   installPath: string;
   packagePayload: Exclude<PackagePayloadManifestReadResult, { status: "present" }>;
 }): PluginPayloadSmokeFailure {
+  if (params.packagePayload.status === "unreadable") {
+    const packageJsonPath = path.join(params.installPath, "package.json");
+    return {
+      pluginId: params.pluginId,
+      installPath: params.installPath,
+      reason: "unreadable-package-json",
+      detail: `Could not read package.json at ${packageJsonPath}: ${params.packagePayload.error}`,
+    };
+  }
   if (params.packagePayload.status === "invalid") {
     return {
       pluginId: params.pluginId,
diff --git a/src/cli/update-cli/post-core-plugin-convergence.test.ts b/src/cli/update-cli/post-core-plugin-convergence.test.ts
@@ -502,6 +502,53 @@ describe("runPostCorePluginConvergence", () => {
     ]);
   });
 
+  it("uses ownership guidance and a coherent update outcome for unreadable package.json", async () => {
+    mocks.repairMissingConfiguredPluginInstalls.mockResolvedValue({
+      changes: [],
+      warnings: [],
+      records: { brave: { source: "npm", installPath: "/p/brave" } },
+    });
+    mocks.runPluginPayloadSmokeCheck.mockResolvedValue({
+      checked: ["brave"],
+      failures: [
+        {
+          pluginId: "brave",
+          installPath: "/p/brave",
+          reason: "unreadable-package-json",
+          detail: "Could not read package.json at /p/brave/package.json: EACCES: permission denied",
+        },
+      ],
+    });
+
+    const result = await runPostCorePluginConvergence({
+      cfg: {
+        plugins: { entries: { brave: { enabled: true } } },
+      } as unknown as OpenClawConfig,
+      env: {},
+    });
+
+    const message =
+      'Plugin "brave" failed post-core payload smoke check (unreadable-package-json): Could not read package.json at /p/brave/package.json: EACCES: permission denied';
+    const guidance = [
+      "Fix file access for /p/brave/package.json so it is readable by the user running OpenClaw. For EACCES or EPERM, correct its ownership or permissions; otherwise resolve the reported filesystem I/O error, then retry.",
+      "Run `openclaw plugins inspect brave --runtime --json` for details.",
+    ];
+    expect(result.warnings).toStrictEqual([
+      {
+        pluginId: "brave",
+        reason:
+          "unreadable-package-json: Could not read package.json at /p/brave/package.json: EACCES: permission denied",
+        message,
+        guidance,
+      },
+    ]);
+    expect(convergenceWarningsToOutcomes(result)).toStrictEqual({
+      warnings: result.warnings,
+      outcomes: [{ pluginId: "brave", status: "error", message }],
+      errored: true,
+    });
+  });
+
   it("hands repair's post-mutation records straight to the smoke check (no second disk read)", async () => {
     const records = { brave: { source: "npm" as const, installPath: "/p/brave" } };
     mocks.repairMissingConfiguredPluginInstalls.mockResolvedValue({
diff --git a/src/cli/update-cli/post-core-plugin-convergence.ts b/src/cli/update-cli/post-core-plugin-convergence.ts
@@ -1,4 +1,5 @@
 // Reconciles configured plugin installs after the core package update has completed.
+import path from "node:path";
 import { repairMissingConfiguredPluginInstalls } from "../../commands/doctor/shared/missing-configured-plugin-install.js";
 import { UPDATE_POST_CORE_CONVERGENCE_ENV } from "../../commands/doctor/shared/update-phase.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
@@ -49,6 +50,19 @@ const REPAIR_GUIDANCE = "Run `openclaw update repair` to retry plugin repair.";
 const inspectGuidance = (pluginId: string) =>
   `Run \`openclaw plugins inspect ${pluginId} --runtime --json\` for details.`;
 
+function smokeFailureGuidance(failure: PluginPayloadSmokeFailure): string[] {
+  if (failure.reason !== "unreadable-package-json") {
+    return [REPAIR_GUIDANCE, inspectGuidance(failure.pluginId)];
+  }
+  const packageJsonPath = failure.installPath
+    ? path.join(failure.installPath, "package.json")
+    : "the plugin package.json";
+  return [
+    `Fix file access for ${packageJsonPath} so it is readable by the user running OpenClaw. For EACCES or EPERM, correct its ownership or permissions; otherwise resolve the reported filesystem I/O error, then retry.`,
+    inspectGuidance(failure.pluginId),
+  ];
+}
+
 async function repairManagedNpmOpenClawPeerLinks(params: {
   env: NodeJS.ProcessEnv;
 }): Promise<{ changes: string[]; warnings: PostCoreConvergenceWarning[] }> {
@@ -156,7 +170,7 @@ export async function runPostCorePluginConvergence(params: {
       pluginId: failure.pluginId,
       reason: `${failure.reason}: ${failure.detail}`,
       message: `Plugin "${failure.pluginId}" failed post-core payload smoke check (${failure.reason}): ${failure.detail}`,
-      guidance: [REPAIR_GUIDANCE, inspectGuidance(failure.pluginId)],
+      guidance: smokeFailureGuidance(failure),
     });
   }
 
diff --git a/src/commands/doctor-config-preflight.state-migration.test.ts b/src/commands/doctor-config-preflight.state-migration.test.ts
@@ -563,7 +563,9 @@ describe("runDoctorConfigPreflight state migration", () => {
         invalidConfigNote: false,
         requireStartupMigrationCheckpoint: true,
       }),
-    ).rejects.toThrow("refusing to report the gateway ready");
+    ).rejects.toThrow(
+      "OpenClaw startup migrations did not complete cleanly; refusing to report the gateway ready.",
+    );
 
     expect(recordSuccessfulStartupMigrations).not.toHaveBeenCalled();
     expect(startupMigrationLeaseRelease).toHaveBeenCalledOnce();
@@ -621,7 +623,9 @@ describe("runDoctorConfigPreflight state migration", () => {
         invalidConfigNote: false,
         requireStartupMigrationCheckpoint: true,
       }),
-    ).rejects.toThrow("failed post-core payload smoke check");
+    ).rejects.toThrow(
+      'OpenClaw plugin verification failed; refusing to report the gateway ready.\n- Plugin "discord" failed post-core payload smoke check',
+    );
 
     expect(recordSuccessfulStartupMigrations).not.toHaveBeenCalled();
     expect(startupMigrationLeaseRelease).toHaveBeenCalledOnce();
diff --git a/src/commands/doctor-config-preflight.ts b/src/commands/doctor-config-preflight.ts
@@ -141,10 +141,15 @@ function noteStateMigrationResult(result: {
   }
 }
 
+type StartupPluginVerificationDiagnostic = {
+  kind: "plugin-verification";
+  messages: string[];
+};
+
 async function runStartupUpgradeConvergence(params: {
   cfg: OpenClawConfig;
   env: NodeJS.ProcessEnv;
-}): Promise<string[]> {
+}): Promise<StartupPluginVerificationDiagnostic | null> {
   const { planStartupPluginConvergence } = await measureStartupPreflightStep(
     "plugin-plan-import",
     () => import("./doctor/shared/startup-plugin-convergence-plan.js"),
@@ -156,7 +161,7 @@ async function runStartupUpgradeConvergence(params: {
     }),
   );
   if (!plan.required) {
-    return [];
+    return null;
   }
   const { runPostCorePluginConvergence } = await measureStartupPreflightStep(
     "plugin-convergence-import",
@@ -185,7 +190,7 @@ async function runStartupUpgradeConvergence(params: {
   if (warnings.length > 0) {
     note(warnings.map((warning) => `- ${warning}`).join("\n"), "Doctor warnings");
   }
-  return warnings;
+  return warnings.length > 0 ? { kind: "plugin-verification", messages: warnings } : null;
 }
 
 function formatStartupMigrationFailure(params: { warnings: string[]; blockers: string[] }): string {
@@ -200,6 +205,16 @@ function formatStartupMigrationFailure(params: { warnings: string[]; blockers: s
   ].join("\n");
 }
 
+function formatStartupPluginVerificationFailure(
+  diagnostic: StartupPluginVerificationDiagnostic,
+): string {
+  return [
+    "OpenClaw plugin verification failed; refusing to report the gateway ready.",
+    ...diagnostic.messages.map((message) => `- ${message}`),
+    "Resolve the plugin verification errors above, then restart the container.",
+  ].join("\n");
+}
+
 function throwStartupMigrationGuardRejected(): never {
   throw new Error(
     "OpenClaw startup migrations were skipped because the selected config changed during startup; refusing to report the gateway ready. Retry startup so the new config can be validated.",
@@ -460,20 +475,29 @@ export async function runDoctorConfigPreflight(
           ? startupMigrationHeartbeatError
           : new Error("OpenClaw startup migration lease heartbeat failed.");
       }
-      const blockers =
-        startupMigrationWarnings.length > 0
-          ? []
-          : snapshot.valid
-            ? await runStartupUpgradeConvergence({ cfg: baseConfig, env: process.env })
-            : ['OpenClaw config is invalid; run "openclaw doctor --fix" before startup.'];
-      if (startupMigrationWarnings.length > 0 || blockers.length > 0) {
+      if (startupMigrationWarnings.length > 0) {
         throw new Error(
           formatStartupMigrationFailure({
             warnings: startupMigrationWarnings,
-            blockers,
+            blockers: [],
           }),
         );
       }
+      if (!snapshot.valid) {
+        throw new Error(
+          formatStartupMigrationFailure({
+            warnings: [],
+            blockers: ['OpenClaw config is invalid; run "openclaw doctor --fix" before startup.'],
+          }),
+        );
+      }
+      const pluginVerificationDiagnostic = await runStartupUpgradeConvergence({
+        cfg: baseConfig,
+        env: process.env,
+      });
+      if (pluginVerificationDiagnostic) {
+        throw new Error(formatStartupPluginVerificationFailure(pluginVerificationDiagnostic));
+      }
       startupCheckpoint?.recordSuccessfulStartupMigrations({
         env: startupMigrationEnv,
         lease: startupMigrationLease,
