fix(memory): warn when qmd binary is missing (#57467)

* fix(memory): warn when qmd binary is missing

* fix(memory): avoid probing cached qmd managers

* docs(memory): clarify qmd doctor probe behavior

* fix(memory): probe qmd from agent workspace

packages/memory-host-sdk/src/host/qmd-process.test.ts

@@ -1,30 +1,51 @@
+import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { resolveCliSpawnInvocation } from "./qmd-process.js";
+
+const spawnMock = vi.hoisted(() => vi.fn());
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...actual,
+    spawn: spawnMock,
+  };
+});
+
+import { checkQmdBinaryAvailability, resolveCliSpawnInvocation } from "./qmd-process.js";
+
+function createMockChild() {
+  const child = new EventEmitter() as EventEmitter & {
+    kill: ReturnType<typeof vi.fn>;
+  };
+  child.kill = vi.fn();
+  return child;
+}
+
+let tempDir = "";
+let platformSpy: { mockRestore(): void } | null = null;
+const originalPath = process.env.PATH;
+const originalPathExt = process.env.PATHEXT;
+
+beforeEach(async () => {
+  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-qmd-win-spawn-"));
+  platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("win32");
+});
+
+afterEach(async () => {
+  platformSpy?.mockRestore();
+  process.env.PATH = originalPath;
+  process.env.PATHEXT = originalPathExt;
+  spawnMock.mockReset();
+  if (tempDir) {
+    await fs.rm(tempDir, { recursive: true, force: true });
+    tempDir = "";
+  }
+});
 
 describe("resolveCliSpawnInvocation", () => {
-  let tempDir = "";
-  let platformSpy: { mockRestore(): void } | null = null;
-  const originalPath = process.env.PATH;
-  const originalPathExt = process.env.PATHEXT;
-
-  beforeEach(async () => {
-    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-qmd-win-spawn-"));
-    platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("win32");
-  });
-
-  afterEach(async () => {
-    platformSpy?.mockRestore();
-    process.env.PATH = originalPath;
-    process.env.PATHEXT = originalPathExt;
-    if (tempDir) {
-      await fs.rm(tempDir, { recursive: true, force: true });
-      tempDir = "";
-    }
-  });
-
   it("unwraps npm cmd shims to a direct node entrypoint", async () => {
     const binDir = path.join(tempDir, "node_modules", ".bin");
     const packageDir = path.join(tempDir, "node_modules", "qmd");
@@ -89,3 +110,45 @@ describe("resolveCliSpawnInvocation", () => {
     expect(invocation.shell).not.toBe(true);
   });
 });
+
+describe("checkQmdBinaryAvailability", () => {
+  it("returns available when the qmd process spawns successfully", async () => {
+    const child = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => child.emit("spawn"));
+      return child;
+    });
+
+    await expect(
+      checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
+    ).resolves.toEqual({ available: true });
+    expect(child.kill).toHaveBeenCalled();
+  });
+
+  it("returns unavailable when the qmd process cannot be spawned", async () => {
+    const child = createMockChild();
+    const err = Object.assign(new Error("spawn qmd ENOENT"), { code: "ENOENT" });
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => child.emit("error", err));
+      return child;
+    });
+
+    await expect(
+      checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
+    ).resolves.toEqual({ available: false, error: "spawn qmd ENOENT" });
+  });
+
+  it("does not treat close-before-spawn as a successful availability probe", async () => {
+    const child = createMockChild();
+    const err = Object.assign(new Error("spawn qmd ENOENT"), { code: "ENOENT" });
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => child.emit("close"));
+      queueMicrotask(() => child.emit("error", err));
+      return child;
+    });
+
+    await expect(
+      checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
+    ).resolves.toEqual({ available: false, error: "spawn qmd ENOENT" });
+  });
+});

packages/memory-host-sdk/src/host/qmd-process.ts

@@ -11,6 +11,11 @@ export type CliSpawnInvocation = {
   windowsHide?: boolean;
 };
 
+export type QmdBinaryAvailability = {
+  available: boolean;
+  error?: string;
+};
+
 export function resolveCliSpawnInvocation(params: {
   command: string;
   args: string[];
@@ -28,6 +33,70 @@ export function resolveCliSpawnInvocation(params: {
   return materializeWindowsSpawnProgram(program, params.args);
 }
 
+export async function checkQmdBinaryAvailability(params: {
+  command: string;
+  env: NodeJS.ProcessEnv;
+  cwd?: string;
+  timeoutMs?: number;
+}): Promise<QmdBinaryAvailability> {
+  let spawnInvocation: CliSpawnInvocation;
+  try {
+    spawnInvocation = resolveCliSpawnInvocation({
+      command: params.command,
+      args: [],
+      env: params.env,
+      packageName: "qmd",
+    });
+  } catch (err) {
+    return { available: false, error: formatQmdAvailabilityError(err) };
+  }
+
+  return await new Promise((resolve) => {
+    let settled = false;
+    let didSpawn = false;
+    const finish = (result: QmdBinaryAvailability) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve(result);
+    };
+
+    const child = spawn(spawnInvocation.command, spawnInvocation.argv, {
+      env: params.env,
+      cwd: params.cwd ?? process.cwd(),
+      shell: spawnInvocation.shell,
+      windowsHide: spawnInvocation.windowsHide,
+      stdio: "ignore",
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish({
+        available: false,
+        error: `spawn ${params.command} timed out after ${params.timeoutMs ?? 2_000}ms`,
+      });
+    }, params.timeoutMs ?? 2_000);
+
+    child.once("error", (err) => {
+      finish({ available: false, error: formatQmdAvailabilityError(err) });
+    });
+    child.once("spawn", () => {
+      didSpawn = true;
+      child.kill();
+      finish({ available: true });
+    });
+    child.once("close", () => {
+      if (!didSpawn) {
+        return;
+      }
+      finish({ available: true });
+    });
+  });
+}
+
 export async function runCliCommand(params: {
   commandSummary: string;
   spawnInvocation: CliSpawnInvocation;
@@ -106,3 +175,10 @@ function appendOutputWithCap(
   }
   return { text: appended.slice(-maxChars), truncated: true };
 }
+
+function formatQmdAvailabilityError(err: unknown): string {
+  if (err instanceof Error && err.message) {
+    return err.message;
+  }
+  return String(err);
+}