From 6b82eaa2cd03a969b2bca10bb42fbbae8f2f28d3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 20 May 2026 02:36:28 +0100
Subject: [PATCH] fix(update): carry candidate plugin API version through
 doctor

---
 src/cli/update-cli.test.ts           | 9 +++++++++
 src/cli/update-cli/update-command.ts | 2 ++
 src/commands/doctor.e2e-harness.ts   | 2 +-
 src/infra/update-runner.test.ts      | 1 +
 src/infra/update-runner.ts           | 2 ++
 5 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/cli/update-cli.test.ts b/src/cli/update-cli.test.ts
index 34e96173572..3a3434417e6 100644
--- a/src/cli/update-cli.test.ts
+++ b/src/cli/update-cli.test.ts
@@ -2365,12 +2365,21 @@ describe("update-cli", () => {
         termination: "exit",
       };
     });
+    readPackageVersion.mockImplementation(async (packageRoot: string) => {
+      const manifest = JSON.parse(
+        await fs.readFile(path.join(packageRoot, "package.json"), "utf-8"),
+      ) as { version?: string };
+      return manifest.version ?? "0.0.0";
+    });
 
     await updateCommand({ yes: true });
 
     const doctorCall = doctorCommandCall();
     expect(doctorCall?.[0].slice(1)).toEqual([entryPath, "doctor", "--non-interactive", "--fix"]);
     expect(doctorCall?.[1].cwd).toBe(pkgRoot);
+    expect(
+      (doctorCall?.[1].env as NodeJS.ProcessEnv | undefined)?.OPENCLAW_COMPATIBILITY_HOST_VERSION,
+    ).toBe("2026.5.14");
     expect(defaultRuntime.exit).not.toHaveBeenCalledWith(1);
   });
 
diff --git a/src/cli/update-cli/update-command.ts b/src/cli/update-cli/update-command.ts
index c7dfc414700..8106db65048 100644
--- a/src/cli/update-cli/update-command.ts
+++ b/src/cli/update-cli/update-command.ts
@@ -1403,6 +1403,7 @@ async function runPackageInstallUpdate(params: {
       const entryPath = await resolveGatewayInstallEntrypoint(verifiedPackageRoot);
       if (entryPath) {
         await createUpdateConfigSnapshot();
+        const candidateHostVersion = await readPackageVersion(verifiedPackageRoot);
         return await runUpdateStep({
           name: `${CLI_NAME} doctor`,
           argv: [
@@ -1421,6 +1422,7 @@ async function runPackageInstallUpdate(params: {
             OPENCLAW_UPDATE_IN_PROGRESS: "1",
             [UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR_ENV]: "1",
             [UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV]: "1",
+            OPENCLAW_COMPATIBILITY_HOST_VERSION: candidateHostVersion,
           },
           timeoutMs: params.timeoutMs,
           progress: params.progress,
diff --git a/src/commands/doctor.e2e-harness.ts b/src/commands/doctor.e2e-harness.ts
index 2fb963fbce9..e2a9cc1f22e 100644
--- a/src/commands/doctor.e2e-harness.ts
+++ b/src/commands/doctor.e2e-harness.ts
@@ -499,7 +499,7 @@ export async function arrangeLegacyStateMigrationTest(): Promise<{
 
   detectLegacyStateMigrations.mockClear();
   runLegacyStateMigrations.mockClear();
-  detectLegacyStateMigrations.mockResolvedValueOnce(
+  detectLegacyStateMigrations.mockResolvedValue(
     createLegacyStateMigrationDetectionResult({
       hasLegacySessions: true,
       preview: ["- Legacy sessions detected"],
diff --git a/src/infra/update-runner.test.ts b/src/infra/update-runner.test.ts
index f19f351db73..7f0d9ca2636 100644
--- a/src/infra/update-runner.test.ts
+++ b/src/infra/update-runner.test.ts
@@ -1791,6 +1791,7 @@ describe("runGatewayUpdate", () => {
     expect(result.steps.map((step) => step.name)).toContain("openclaw doctor");
     expect(doctorEnv?.OPENCLAW_UPDATE_IN_PROGRESS).toBe("1");
     expect(doctorEnv?.OPENCLAW_UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE).toBe("1");
+    expect(doctorEnv?.OPENCLAW_COMPATIBILITY_HOST_VERSION).toBe("2.0.0");
   });
 
   it("fails global npm updates when post-update doctor fails", async () => {
diff --git a/src/infra/update-runner.ts b/src/infra/update-runner.ts
index bbe02c6d814..da7817bda81 100644
--- a/src/infra/update-runner.ts
+++ b/src/infra/update-runner.ts
@@ -1477,6 +1477,7 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
           return null;
         }
         const doctorNodePath = await resolveStableNodePath(process.execPath);
+        const candidateHostVersion = await readPackageVersion(verifiedPackageRoot);
         return await runStep({
           runCommand,
           name: "openclaw doctor",
@@ -1486,6 +1487,7 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
           env: {
             OPENCLAW_UPDATE_IN_PROGRESS: "1",
             [UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV]: "1",
+            OPENCLAW_COMPATIBILITY_HOST_VERSION: candidateHostVersion,
           },
           progress,
           stepIndex: 0,