@remnic/core 9.4.0 → 9.4.2

package/src/qmd-preflight.test.ts

@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { abortError } from "./abort-error.js";
+import { QmdClient } from "./qmd.js";
+
+/**
+ * Internals exposed only for preflight testing. Cast once to a NAMED type (not
+ * an inline shape) so the compiler never fabricates a one-off member type; the
+ * unchecked access is scoped to these deliberately-injected seams. Issue #1841.
+ */
+type QmdPreflightInternals = {
+  configuredQmdPath: string | undefined;
+  runVersionProbe: (qmdPath: string, signal?: AbortSignal) => Promise<{ stdout: string; stderr: string }>;
+  logCliProbeWarning: (message: string) => void;
+  probeCli: (options?: {
+    allowAutoUpgrade?: boolean;
+    preserveStateOnFailure?: boolean;
+    signal?: AbortSignal;
+  }) => Promise<boolean>;
+};
+
+const CONFIGURED_PATH = "/opt/qmd/bin/qmd";
+
+/** Build the Node spawn ENOENT error shape (Error carrying `code: "ENOENT"`). */
+function spawnENOENT(qmdPath: string): Error & { code: string } {
+  return Object.assign(new Error(`spawn ${qmdPath} ENOENT`), {
+    code: "ENOENT" as const,
+  });
+}
+
+function timeoutError(): Error & { timedOut: true } {
+  // Mirrors the error runCommandWithTimeout rejects with on deadline: a plain
+  // Error flagged with `timedOut: true` — the structured signal classifyProbeFailure
+  // keys on (never the message text). Issue #1841.
+  return Object.assign(new Error("qmd --version timed out after 8000ms"), {
+    timedOut: true as const,
+  });
+}
+
+/** Wire a fresh client whose probe runner + warning sink are fully scripted. */
+function harness(opts: {
+  configuredBehavior: () => Promise<{ stdout: string; stderr: string }>;
+}): {
+  internals: QmdPreflightInternals;
+  warnings: string[];
+  configuredProbeCalls: () => number;
+} {
+  const client = new QmdClient("memories", 3, {
+    qmdPath: CONFIGURED_PATH,
+    qmdFallbackPaths: [],
+  });
+  const internals = client as unknown as QmdPreflightInternals;
+  const warnings: string[] = [];
+  internals.logCliProbeWarning = (message: string) => {
+    warnings.push(message);
+  };
+  let configuredCalls = 0;
+  internals.runVersionProbe = async (qmdPath: string) => {
+    if (qmdPath === CONFIGURED_PATH) {
+      configuredCalls += 1;
+      return opts.configuredBehavior();
+    }
+    // Any non-configured path (PATH/fallback probing) is a hard miss here so
+    // probeCli returns false without spawning a real qmd binary.
+    throw spawnENOENT(qmdPath);
+  };
+  return {
+    internals,
+    warnings,
+    configuredProbeCalls: () => configuredCalls,
+  };
+}
+
+test("QmdClient preflight: transient timeout retries then succeeds with NO failure warning", async () => {
+  // Two timeouts, then success on the second retry.
+  const scripted: Array<"timeout" | "ok"> = ["timeout", "timeout", "ok"];
+  let i = 0;
+  const { internals, warnings, configuredProbeCalls } = harness({
+    configuredBehavior: async () => {
+      const step = scripted[i++];
+      if (step === "timeout") throw timeoutError();
+      return { stdout: "qmd 1.2.3\n", stderr: "" };
+    },
+  });
+
+  const ok = await internals.probeCli({ allowAutoUpgrade: false });
+
+  assert.equal(ok, true, "configured probe should succeed after retry");
+  assert.equal(configuredProbeCalls(), 3, "initial attempt + 2 retries for transient timeout");
+  assert.deepEqual(warnings, [], "no failure warning emitted when retry succeeds");
+});
+
+test("QmdClient preflight: persistent timeout emits the distinct under-load warning (not 'configured qmdPath failed')", async () => {
+  const { internals, warnings, configuredProbeCalls } = harness({
+    configuredBehavior: async () => {
+      throw timeoutError();
+    },
+  });
+
+  const ok = await internals.probeCli({ allowAutoUpgrade: false });
+
+  assert.equal(ok, false, "exhausted retries fall through to unavailable");
+  assert.equal(configuredProbeCalls(), 3, "initial attempt + 2 retries before declaring transient failure");
+  assert.equal(warnings.length, 1, "exactly one failure warning");
+  const msg = warnings[0] ?? "";
+  assert.match(
+    msg,
+    /version check timed out \(host may be under load\); retried 2 times/,
+    "transient failure uses the under-load wording"
+  );
+  assert.doesNotMatch(msg, /configured qmdPath failed/, "must not read as a generic misconfiguration");
+});
+
+test("QmdClient preflight: genuine ENOENT fails fast (no retry) with the not-found/not-executable warning", async () => {
+  const { internals, warnings, configuredProbeCalls } = harness({
+    configuredBehavior: async () => {
+      throw spawnENOENT(CONFIGURED_PATH);
+    },
+  });
+
+  const ok = await internals.probeCli({ allowAutoUpgrade: false });
+
+  assert.equal(ok, false, "missing binary is unavailable");
+  assert.equal(configuredProbeCalls(), 1, "ENOENT is a hard misconfiguration: never retried");
+  assert.equal(warnings.length, 1, "exactly one failure warning");
+  const msg = warnings[0] ?? "";
+  assert.match(msg, /configured qmdPath not found or not executable/, "missing binary uses the not-found wording");
+  assert.match(msg, /spawn .* ENOENT/, "underlying error detail preserved");
+  assert.doesNotMatch(msg, /timed out|under load/, "must not read as a transient timeout");
+});
+
+test("QmdClient preflight: non-timeout exit-code failure keeps the generic configured-failed message and does not retry", async () => {
+  const { internals, warnings, configuredProbeCalls } = harness({
+    configuredBehavior: async () => {
+      throw new Error("qmd --version exited with code 2");
+    },
+  });
+
+  const ok = await internals.probeCli({ allowAutoUpgrade: false });
+
+  assert.equal(ok, false, "exit-code failure is unavailable");
+  assert.equal(configuredProbeCalls(), 1, "non-transient, non-missing failures are not retried");
+  assert.equal(warnings.length, 1, "exactly one failure warning");
+  const msg = warnings[0] ?? "";
+  assert.match(msg, /configured qmdPath failed/, "ambiguous exit-code failures keep the historical generic wording");
+  assert.doesNotMatch(
+    msg,
+    /timed out|under load|not found or not executable/,
+    "must not be misclassified as timeout or missing"
+  );
+});
+
+test("QmdClient preflight: caller abort emits NO warning and does not retry", async () => {
+  // The caller cancelled (aborted signal + AbortError). Other QMD paths treat
+  // this as non-actionable noise via isCallerCancellation; the configured-path
+  // probe must do the same — no under-load warning, no transient retry. #1841.
+  const controller = new AbortController();
+  controller.abort();
+  const { internals, warnings, configuredProbeCalls } = harness({
+    configuredBehavior: async () => {
+      // A real probe rejects with an AbortError when the caller's signal fires.
+      throw abortError("qmd --version aborted");
+    },
+  });
+
+  const ok = await internals.probeCli({ allowAutoUpgrade: false, signal: controller.signal });
+
+  assert.equal(ok, false, "aborted configured probe falls through to unavailable");
+  assert.equal(configuredProbeCalls(), 1, "caller cancellation never retries");
+  assert.deepEqual(warnings, [], "caller cancellation is silent noise: no operator-facing warning");
+});
+
+test("QmdClient preflight: non-zero exit whose stderr says 'timed out'/'not found' is classified 'other' (not transient/missing)", async () => {
+  // Mirrors runCommandWithTimeout's non-zero-exit rejection: the child's stderr
+  // (here containing "timed out" and "not found") is embedded in the message.
+  // A healthy binary can emit those words in error text; they must NOT upgrade
+  // the failure to transient/missing. classifyProbeFailure keys on structured
+  // signals, so this generic exit-code failure stays 'other'. Issue #1841.
+  const { internals, warnings, configuredProbeCalls } = harness({
+    configuredBehavior: async () => {
+      throw new Error("qmd --version failed (code 2): error: model timed out while loading; config not found");
+    },
+  });
+
+  const ok = await internals.probeCli({ allowAutoUpgrade: false });
+
+  assert.equal(ok, false, "exit-code failure is unavailable");
+  assert.equal(configuredProbeCalls(), 1, "embedded-stderr failure is not transient — no retry");
+  assert.equal(warnings.length, 1, "exactly one failure warning");
+  const msg = warnings[0] ?? "";
+  assert.match(msg, /configured qmdPath failed/, "classified as generic 'other'");
+  assert.doesNotMatch(
+    msg,
+    /under load|not found or not executable/,
+    "must not misclassify embedded-stderr words as transient/missing"
+  );
+});

package/src/qmd-preflight.ts

@@ -0,0 +1,167 @@
+/**
+ * QMD version-check PREFLIGHT / probe-classification helpers.
+ *
+ * Pure, self-contained functions extracted from qmd.ts (issue #1841) so the
+ * QmdClient class file stays under the structural-ratchet LOC ceiling. These
+ * cover two related concerns of the startup preflight:
+ *
+ * 1. VERSION parsing/comparison — turning `qmd --version` output into a tuple,
+ *    comparing against the supported target, and resolving feature capability
+ *    flags from the parsed version.
+ * 2. PROBE failure classification — distinguishing a slow/overloaded binary
+ *    (transient → retry) from a genuine misconfiguration (ENOENT/EACCES → fail
+ *    fast) using STRUCTURED signals, never the error message.
+ *
+ * No behavioral change from qmd.ts round 1 (issue #1841): structured-signal
+ * classification (code=ENOENT/EACCES=>missing, timedOut flag=>transient,
+ * caller-cancel silenced, non-zero-exit=>other); backoff [300,800].
+ */
+import { isAbortError } from "./abort-error.js";
+import type { QmdCapabilities, QmdVersionTuple } from "./qmd.js";
+
+// Deadline (ms) for a single `qmd --version` probe.
+export const QMD_PROBE_TIMEOUT_MS = 8_000;
+
+// Backoff schedule (ms) for retrying a TRANSIENT (timeout/abort) version-check
+// probe of a CONFIGURED qmdPath before declaring it failed. A binary that
+// resolved and ran before is more likely slow under load than gone, so we retry
+// transient failures but NOT ENOENT/EACCES (hard misconfiguration, fail fast).
+// Length == number of retries after the initial attempt. Issue #1841.
+export const QMD_PROBE_RETRY_BACKOFF_MS = [300, 800];
+
+export const QMD_SUPPORTED_VERSION = "2.5.3";
+
+/**
+ * Classify a `qmd --version` probe failure so the preflight can distinguish a
+ * slow/overloaded binary (a genuine deadline timeout) from a real
+ * misconfiguration (ENOENT/EACCES — the configured path is missing or not
+ * executable). Only transient failures are retried; missing binaries fail fast.
+ *
+ * Classification keys on STRUCTURED signals, never the error *message*: a
+ * non-zero-exit failure embeds the child's stderr in its message, so scanning
+ * that text for "abort"/"timed out"/"not found" would misclassify a healthy
+ * binary. The structured signals are: `code` (ENOENT/EACCES) for missing; the
+ * `timedOut` flag set by `runCommandWithTimeout` for a genuine timeout; an
+ * AbortError name for a deadline/abort under load. Issue #1841.
+ */
+export type QmdProbeFailureKind = "transient" | "missing" | "other";
+export function classifyProbeFailure(err: unknown): QmdProbeFailureKind {
+  if (err && typeof err === "object") {
+    // Node spawn failures carry a structured `code`: ENOENT (not found) /
+    // EACCES (not executable).
+    if ("code" in err) {
+      const code = err.code;
+      if (code === "ENOENT" || code === "EACCES") return "missing";
+    }
+    // runCommandWithTimeout flags a genuine deadline breach with `timedOut`.
+    if ("timedOut" in err && err.timedOut === true) return "transient";
+  }
+  // An AbortError reaching here is a deadline/abort under load → transient.
+  // (Caller cancellation is intercepted by the retry loop before this runs.)
+  if (isAbortError(err)) return "transient";
+  // Anything else — including a non-zero exit whose message embeds stderr — is
+  // a generic failure: never scan the message to upgrade/downgrade it.
+  return "other";
+}
+
+export function parseQmdVersion(version: string | null): QmdVersionTuple | null {
+  if (!version) return null;
+  const match = version.match(/v?(\d{1,10})\.(\d{1,10})\.(\d{1,10})/i);
+  if (!match) return null;
+  return [
+    Number.parseInt(match[1] ?? "0", 10),
+    Number.parseInt(match[2] ?? "0", 10),
+    Number.parseInt(match[3] ?? "0", 10),
+  ];
+}
+
+export function parseQmdVersionOutput(stdout: string, stderr: string): string | null {
+  const lines = `${stdout}\n${stderr}`
+    .split("\n")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (lines.length === 0) return null;
+  const semanticLines = lines.filter((line) => parseQmdVersion(line) !== null);
+  if (semanticLines.length === 0) return lines[0] ?? null;
+  return semanticLines.find((line) => /\bqmd\b/i.test(line)) ?? semanticLines[0] ?? null;
+}
+
+export function compareQmdVersions(left: QmdVersionTuple | null, right: QmdVersionTuple | null): number {
+  if (!left && !right) return 0;
+  if (!left) return -1;
+  if (!right) return 1;
+  for (let i = 0; i < 3; i += 1) {
+    if ((left[i] ?? 0) > (right[i] ?? 0)) return 1;
+    if ((left[i] ?? 0) < (right[i] ?? 0)) return -1;
+  }
+  return 0;
+}
+
+export function versionAtLeast(current: QmdVersionTuple | null, target: QmdVersionTuple): boolean {
+  return compareQmdVersions(current, target) >= 0;
+}
+
+export function resolveQmdCapabilities(version: string | null): QmdCapabilities {
+  const parsedVersion = parseQmdVersion(version);
+  const atLeast = (target: QmdVersionTuple): boolean => versionAtLeast(parsedVersion, target);
+  return {
+    version,
+    parsedVersion,
+    stableSdk: atLeast([2, 0, 0]),
+    unifiedSearch: atLeast([2, 0, 0]),
+    getDocumentBody: atLeast([2, 0, 0]),
+    maintenanceApi: atLeast([2, 0, 0]),
+    legacySkillInstall: atLeast([2, 0, 1]),
+    intentHints: atLeast([1, 1, 5]),
+    explainTraces: atLeast([1, 1, 2]),
+    candidateLimit: atLeast([1, 1, 2]),
+    v2McpQueryTool: atLeast([2, 0, 0]),
+    structuredSearches: atLeast([2, 0, 0]),
+    queryRerankToggle: atLeast([2, 1, 0]),
+    chunkStrategy: atLeast([2, 1, 0]),
+    qmdBench: atLeast([2, 1, 0]),
+    perCollectionModels: atLeast([2, 1, 0]),
+    jsonLineNumbers: atLeast([2, 1, 0]),
+    editorLinks: atLeast([2, 1, 0]),
+    doctor: atLeast([2, 5, 0]),
+    versionedSkills: atLeast([2, 5, 0]),
+    absoluteSnippetLines: atLeast([2, 5, 0]),
+    fullQueryOutput: atLeast([2, 5, 0]),
+    forceCpu: atLeast([2, 5, 0]),
+    gpuBackendOverride: atLeast([2, 5, 0]),
+    embedParallelism: atLeast([2, 5, 0]),
+    modelEnvConsistency: atLeast([2, 5, 0]),
+    scopedEmbed: atLeast([2, 5, 0]),
+    safeStatusDeviceProbe: atLeast([2, 5, 0]),
+    mcpIndexSelection: atLeast([2, 5, 0]),
+    outputFormatFlag: atLeast([2, 5, 3]),
+  };
+}
+
+export function shouldAutoUpgradeQmd(
+  installedVersion: string | null,
+  supportedVersion: string = QMD_SUPPORTED_VERSION
+): boolean {
+  const installed = parseQmdVersion(installedVersion);
+  const supported = parseQmdVersion(supportedVersion);
+  if (!installed || !supported) return false;
+  return compareQmdVersions(installed, supported) < 0;
+}
+
+export function getQmdPostInstallProbeTargets(
+  qmdPath: string,
+  qmdPathSource: "configured" | "auto-path" | "auto-fallback"
+): Array<{ qmdPath: string; source: "auto-path" | "auto-fallback" }> {
+  const targets: Array<{ qmdPath: string; source: "auto-path" | "auto-fallback" }> = [
+    { qmdPath: "qmd", source: "auto-path" },
+  ];
+  const normalizedPath = qmdPath.trim();
+  if (qmdPathSource === "auto-fallback" && normalizedPath.length > 0 && normalizedPath !== "qmd") {
+    targets.push({ qmdPath: normalizedPath, source: "auto-fallback" });
+  }
+  return targets;
+}
+
+export function qmdVersionToString(version: QmdVersionTuple): string {
+  return `${version[0]}.${version[1]}.${version[2]}`;
+}

package/src/qmd.ts

@@ -18,6 +18,33 @@ import {
 } from "./search/port.js";
 import { launchProcess, type CommandChildProcess } from "./runtime/child-process.js";
 import { mergeEnv } from "./runtime/env.js";
+import {
+  classifyProbeFailure,
+  compareQmdVersions,
+  getQmdPostInstallProbeTargets,
+  parseQmdVersion,
+  parseQmdVersionOutput,
+  QMD_PROBE_RETRY_BACKOFF_MS,
+  QMD_PROBE_TIMEOUT_MS,
+  QMD_SUPPORTED_VERSION,
+  qmdVersionToString,
+  resolveQmdCapabilities,
+  shouldAutoUpgradeQmd,
+  versionAtLeast,
+  type QmdProbeFailureKind,
+} from "./qmd-preflight.js";
+// Re-export version-check / probe-preflight helpers (moved to qmd-preflight.ts,
+// issue #1841) so existing imports from "./qmd.js" keep resolving.
+export {
+  compareQmdVersions,
+  getQmdPostInstallProbeTargets,
+  parseQmdVersion,
+  parseQmdVersionOutput,
+  QMD_SUPPORTED_VERSION,
+  resolveQmdCapabilities,
+  shouldAutoUpgradeQmd,
+  versionAtLeast,
+};
 
 export interface QmdClientOptions {
   slowLog?: { enabled: boolean; thresholdMs: number };
@@ -133,11 +160,9 @@ const QMD_TIMEOUT_MS = 30_000;
 // `qmdDaemonTimeoutMs` config knob (issue #1335), e.g. to give CPU-only HyDE
 // queries more headroom. The effective value lives in `this.daemonTimeoutMs`.
 const QMD_DAEMON_TIMEOUT_MS = 8_000;
-const QMD_PROBE_TIMEOUT_MS = 8_000;
 const QMD_UPDATE_BACKOFF_MS = 15 * 60 * 1000; // 15m
 const QMD_EMBED_BACKOFF_MS = 60 * 60 * 1000; // 60m
 const QMD_CLI_WARN_THROTTLE_MS = 15 * 60 * 1000; // 15m
-export const QMD_SUPPORTED_VERSION = "2.5.3";
 const QMD_PACKAGE_NAME = "@tobilu/qmd";
 const QMD_AUTO_UPGRADE_TIMEOUT_MS = 120_000;
 const QMD_AUTO_UPGRADE_CHECK_INTERVAL_MS = 24 * 60 * 60_000;
@@ -269,118 +294,6 @@ function isVectorDimensionMismatchError(err: unknown): boolean {
   );
 }
 
-export function parseQmdVersion(version: string | null): QmdVersionTuple | null {
-  if (!version) return null;
-  const match = version.match(/v?(\d{1,10})\.(\d{1,10})\.(\d{1,10})/i);
-  if (!match) return null;
-  return [
-    Number.parseInt(match[1] ?? "0", 10),
-    Number.parseInt(match[2] ?? "0", 10),
-    Number.parseInt(match[3] ?? "0", 10),
-  ];
-}
-
-export function parseQmdVersionOutput(stdout: string, stderr: string): string | null {
-  const lines = `${stdout}\n${stderr}`
-    .split("\n")
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
-  if (lines.length === 0) return null;
-  const semanticLines = lines.filter((line) => parseQmdVersion(line) !== null);
-  if (semanticLines.length === 0) return lines[0] ?? null;
-  return semanticLines.find((line) => /\bqmd\b/i.test(line)) ?? semanticLines[0] ?? null;
-}
-
-export function compareQmdVersions(
-  left: QmdVersionTuple | null,
-  right: QmdVersionTuple | null,
-): number {
-  if (!left && !right) return 0;
-  if (!left) return -1;
-  if (!right) return 1;
-  for (let i = 0; i < 3; i += 1) {
-    if ((left[i] ?? 0) > (right[i] ?? 0)) return 1;
-    if ((left[i] ?? 0) < (right[i] ?? 0)) return -1;
-  }
-  return 0;
-}
-
-export function versionAtLeast(
-  current: QmdVersionTuple | null,
-  target: QmdVersionTuple,
-): boolean {
-  return compareQmdVersions(current, target) >= 0;
-}
-
-export function resolveQmdCapabilities(version: string | null): QmdCapabilities {
-  const parsedVersion = parseQmdVersion(version);
-  const atLeast = (target: QmdVersionTuple): boolean => versionAtLeast(parsedVersion, target);
-  return {
-    version,
-    parsedVersion,
-    stableSdk: atLeast([2, 0, 0]),
-    unifiedSearch: atLeast([2, 0, 0]),
-    getDocumentBody: atLeast([2, 0, 0]),
-    maintenanceApi: atLeast([2, 0, 0]),
-    legacySkillInstall: atLeast([2, 0, 1]),
-    intentHints: atLeast([1, 1, 5]),
-    explainTraces: atLeast([1, 1, 2]),
-    candidateLimit: atLeast([1, 1, 2]),
-    v2McpQueryTool: atLeast([2, 0, 0]),
-    structuredSearches: atLeast([2, 0, 0]),
-    queryRerankToggle: atLeast([2, 1, 0]),
-    chunkStrategy: atLeast([2, 1, 0]),
-    qmdBench: atLeast([2, 1, 0]),
-    perCollectionModels: atLeast([2, 1, 0]),
-    jsonLineNumbers: atLeast([2, 1, 0]),
-    editorLinks: atLeast([2, 1, 0]),
-    doctor: atLeast([2, 5, 0]),
-    versionedSkills: atLeast([2, 5, 0]),
-    absoluteSnippetLines: atLeast([2, 5, 0]),
-    fullQueryOutput: atLeast([2, 5, 0]),
-    forceCpu: atLeast([2, 5, 0]),
-    gpuBackendOverride: atLeast([2, 5, 0]),
-    embedParallelism: atLeast([2, 5, 0]),
-    modelEnvConsistency: atLeast([2, 5, 0]),
-    scopedEmbed: atLeast([2, 5, 0]),
-    safeStatusDeviceProbe: atLeast([2, 5, 0]),
-    mcpIndexSelection: atLeast([2, 5, 0]),
-    outputFormatFlag: atLeast([2, 5, 3]),
-  };
-}
-
-export function shouldAutoUpgradeQmd(
-  installedVersion: string | null,
-  supportedVersion: string = QMD_SUPPORTED_VERSION,
-): boolean {
-  const installed = parseQmdVersion(installedVersion);
-  const supported = parseQmdVersion(supportedVersion);
-  if (!installed || !supported) return false;
-  return compareQmdVersions(installed, supported) < 0;
-}
-
-export function getQmdPostInstallProbeTargets(
-  qmdPath: string,
-  qmdPathSource: "configured" | "auto-path" | "auto-fallback",
-): Array<{ qmdPath: string; source: "auto-path" | "auto-fallback" }> {
-  const targets: Array<{ qmdPath: string; source: "auto-path" | "auto-fallback" }> = [
-    { qmdPath: "qmd", source: "auto-path" },
-  ];
-  const normalizedPath = qmdPath.trim();
-  if (
-    qmdPathSource === "auto-fallback" &&
-    normalizedPath.length > 0 &&
-    normalizedPath !== "qmd"
-  ) {
-    targets.push({ qmdPath: normalizedPath, source: "auto-fallback" });
-  }
-  return targets;
-}
-
-function qmdVersionToString(version: QmdVersionTuple): string {
-  return `${version[0]}.${version[1]}.${version[2]}`;
-}
-
 function normalizeSearchOptions(options?: SearchQueryOptions): SearchQueryOptions | undefined {
   if (!options) return undefined;
   const intent = typeof options.intent === "string" ? options.intent.trim() : "";
@@ -671,7 +584,13 @@ function runCommandWithTimeout(
       settled = true;
       cleanup();
       child.kill("SIGKILL");
-      reject(new Error(`${label} timed out after ${options.timeoutMs}ms`));
+      // Flag the deadline breach so classifyProbeFailure can tell a genuine
+      // timeout from a non-zero-exit error whose message merely embeds stderr.
+      reject(
+        Object.assign(new Error(`${label} timed out after ${options.timeoutMs}ms`), {
+          timedOut: true as const,
+        }),
+      );
     }, options.timeoutMs);
     const onAbort = () => {
       if (settled) return;
@@ -1437,6 +1356,18 @@ export class QmdClient implements SearchBackend {
     }
   }
 
+  /**
+   * Run a single `qmd --version` probe against `qmdPath`. Extracted as its own
+   * method so tests can inject a fake probe runner that exercises the preflight
+   * retry/classification paths without spawning a real qmd binary. Issue #1841.
+   */
+  private runVersionProbe(
+    qmdPath: string,
+    signal?: AbortSignal,
+  ): Promise<{ stdout: string; stderr: string }> {
+    return runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, qmdPath, signal, this.qmdRuntimeEnv);
+  }
+
   private async probeCli(
     options: {
       allowAutoUpgrade?: boolean;
@@ -1490,24 +1421,79 @@ export class QmdClient implements SearchBackend {
     };
 
     if (this.configuredQmdPath) {
-      try {
-        const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, this.configuredQmdPath, options.signal, this.qmdRuntimeEnv);
-        await recordProbeSuccess(result, this.configuredQmdPath, "configured");
-        return true;
-      } catch (err) {
-        markProbeFailure(err);
-        configuredProbeFailure = this.lastCliProbeError;
-        // Do not hard-fail here: fall through to PATH/fallback probing.
-        // This keeps recall healthy even when configured path is stale.
-        this.logCliProbeWarning(
-          `QMD: configured qmdPath failed (${this.configuredQmdPath}): ${this.lastCliProbeError}`,
-        );
+      const configuredPath = this.configuredQmdPath;
+      // Retry only TRANSIENT (timeout/abort) probes of the configured path: a
+      // binary that resolved and ran before is more likely slow under load than
+      // gone. ENOENT/EACCES is a hard misconfiguration and must fail fast.
+      // Issue #1841.
+      let failureKind: QmdProbeFailureKind = "other";
+      let retries = 0;
+      let callerCancelled = false;
+      for (let attempt = 0; attempt <= QMD_PROBE_RETRY_BACKOFF_MS.length; attempt += 1) {
+        try {
+          const result = await this.runVersionProbe(configuredPath, options.signal);
+          await recordProbeSuccess(result, configuredPath, "configured");
+          return true;
+        } catch (err) {
+          markProbeFailure(err);
+          configuredProbeFailure = this.lastCliProbeError;
+          // Detect CALLER cancellation FIRST: an aborted signal / AbortError is
+          // non-actionable noise — the caller chose to stop. Other QMD paths
+          // treat it via `isCallerCancellation`; do the same here so a cancelled
+          // probe never reads as a transient host-load failure. Issue #1841.
+          if (isCallerCancellation(err, options.signal)) {
+            callerCancelled = true;
+            break;
+          }
+          failureKind = classifyProbeFailure(err);
+          // Never retry a hard misconfiguration (missing/not-executable) — only
+          // transient slowness. (Caller cancellation is handled above.)
+          if (
+            failureKind === "transient" &&
+            attempt < QMD_PROBE_RETRY_BACKOFF_MS.length
+          ) {
+            try {
+              await sleepWithSignal(
+                QMD_PROBE_RETRY_BACKOFF_MS[attempt] ?? 500,
+                options.signal,
+              );
+            } catch {
+              // Aborted mid-backoff: caller cancelled — stop, emit no warning.
+              callerCancelled = true;
+              break;
+            }
+            retries += 1;
+            continue;
+          }
+          break;
+        }
+      }
+      // Distinct operator-facing warnings so a slow binary is not mistaken for
+      // a misconfiguration (and vice versa). Do not hard-fail here: fall through
+      // to PATH/fallback probing so recall stays healthy when config is stale.
+      // Caller cancellation is silent noise (issue #1841): suppress all warnings
+      // for it exactly as the other QMD paths do.
+      if (!callerCancelled) {
+        if (failureKind === "transient") {
+          this.logCliProbeWarning(
+            `QMD: qmdPath ${configuredPath} version check timed out (host may be under load); retried ${retries} time${retries === 1 ? "" : "s"}`,
+          );
+        } else if (failureKind === "missing") {
+          this.logCliProbeWarning(
+            `QMD: configured qmdPath not found or not executable (${configuredPath}): ${this.lastCliProbeError}`,
+          );
+        } else {
+          // Preserve the historical generic message for exit-code/other failures.
+          this.logCliProbeWarning(
+            `QMD: configured qmdPath failed (${configuredPath}): ${this.lastCliProbeError}`,
+          );
+        }
       }
     }
 
     // Try PATH first
     try {
-      const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, "qmd", options.signal, this.qmdRuntimeEnv);
+      const result = await this.runVersionProbe("qmd", options.signal);
       await recordProbeSuccess(result, "qmd", "auto-path");
       return true;
     } catch (err) {
@@ -1515,7 +1501,7 @@ export class QmdClient implements SearchBackend {
       // Try fallback paths
       for (const fallbackPath of this.qmdFallbackPaths) {
         try {
-          const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, fallbackPath, options.signal, this.qmdRuntimeEnv);
+          const result = await this.runVersionProbe(fallbackPath, options.signal);
           await recordProbeSuccess(result, fallbackPath, "auto-fallback");
           log.info(`QMD: found at ${fallbackPath}`);
           return true;