@remnic/core 9.3.771 → 9.4.1

package/src/memory-projection-store.ts

@@ -12,7 +12,10 @@ import type {
   MemoryProjectionCurrentState,
   MemoryStatus,
 } from "./types.js";
+import { log } from "./logger.js";
 import {
+  displayErrorDetail,
+  isLikelyBetterSqlite3NativeBindingError,
   openBetterSqlite3,
   type BetterSqlite3Database,
 } from "./runtime/better-sqlite.js";
@@ -314,14 +317,188 @@ export function initializeMemoryProjectionDb(db: BetterSqlite3Database): void {
     .run("schemaVersion", String(MEMORY_PROJECTION_SCHEMA_VERSION));
 }
 
+// Test seam (issue #1829): the readonly projection opener is overridable so
+// tests can inject an ABI-style throw against a PRESENT file without faking a
+// corrupt native binding. Default delegates to the shared opener.
+type ProjectionReadonlyOpener = typeof openBetterSqlite3;
+let projectionReadonlyOpener: ProjectionReadonlyOpener = openBetterSqlite3;
+
+/** @internal Test seam: override the readonly projection opener; returns a restore fn. */
+export function __setProjectionReadonlyOpenerForTest(
+  opener: ProjectionReadonlyOpener | null,
+): () => void {
+  const previous = projectionReadonlyOpener;
+  projectionReadonlyOpener = opener ?? openBetterSqlite3;
+  return () => {
+    projectionReadonlyOpener = previous;
+  };
+}
+
+// Rate-limited suppression for open failures — mirrors warnProjectionFallback
+// in storage-guards.ts (5-min dedup per memoryDir). A present-but-unopenable
+// projection is a real failure that must surface, but it repeats on every
+// browse, so the log is throttled to keep output actionable (issue #1829).
+const PROJECTION_OPEN_FAILURE_LOG_INTERVAL_MS = 5 * 60_000;
+const projectionOpenFailureLoggedAt = new Map<string, number>();
+
+/** @internal Test seam: clear the rate-limit dedup map. */
+export function __resetProjectionOpenFailureSuppressionForTest(): void {
+  projectionOpenFailureLoggedAt.clear();
+}
+
+function logProjectionOpenFailure(memoryDir: string, error: unknown): void {
+  const now = Date.now();
+  const warnedAt = projectionOpenFailureLoggedAt.get(memoryDir) ?? 0;
+  if (now - warnedAt < PROJECTION_OPEN_FAILURE_LOG_INTERVAL_MS) return;
+  projectionOpenFailureLoggedAt.set(memoryDir, now);
+  // Path-free detail only (rule 11 / CodeQL js/stack-trace-exposure): the raw
+  // message can embed absolute loader paths; displayErrorDetail returns class +
+  // code. This is the DISTINCT signal that was missing before #1829, when a
+  // wrong-ABI build collapsed into the same silent null as a missing file.
+  const detail = displayErrorDetail(error);
+  const nativeMismatch = isLikelyBetterSqlite3NativeBindingError(error);
+  const detailSuffix = detail ? ` (${detail})` : "";
+  const abiSuffix = nativeMismatch
+    ? " — native binding built for the wrong Node.js ABI; rebuild better-sqlite3 for this process"
+    : "";
+  log.warn(
+    `storage.memory-projection: index present but could not be opened${detailSuffix}${abiSuffix}; falling back to full-corpus scan`,
+  );
+}
+
 function openProjectionReadonly(memoryDir: string): BetterSqlite3Database | null {
   const dbPath = getMemoryProjectionPath(memoryDir);
+  // A MISSING file is a normal fallback (cold install, never built). A file
+  // that EXISTS but cannot open (wrong ABI / corrupt / bad perms) is a real
+  // failure that must surface (issue #1829): previously both collapsed into
+  // the same silent null, hiding native-binding mismatches behind 17-27s
+  // full-corpus scans on every memory list.
+  if (!fs.existsSync(dbPath)) return null;
   try {
-    return openBetterSqlite3(dbPath, { readonly: true, fileMustExist: true });
-  } catch {
+    return projectionReadonlyOpener(dbPath, { readonly: true, fileMustExist: true });
+  } catch (error) {
+    logProjectionOpenFailure(memoryDir, error);
     return null;
   }
 }
+
+export type ProjectionHealthState = "absent" | "openable" | "present-but-invalid" | "unopenable";
+
+export interface ProjectionHealthProbe {
+  state: ProjectionHealthState;
+  /** Path-free detail (class + code) when state !== "absent"/"openable"; "" otherwise. */
+  detail: string;
+  /** true when the open failure is classified as a native-binding ABI mismatch. */
+  nativeBindingMismatch: boolean;
+}
+
+/**
+ * Confirm the projection schema is present and queryable, not just that the
+ * sqlite file opens (issue #1848 round 2). A file that opens but has the
+ * projection tables missing — or is corrupt and only fails on first statement
+ * — previously reported `openable`/ok, so `remnic doctor` said healthy while
+ * browse silently fell back to full-corpus scans. `memory_current` is the
+ * core browse table; if it is absent or unreadable the projection cannot
+ * serve any query. Throws so the probe can report a distinct state.
+ */
+// Named so displayErrorDetail surfaces a clear, path-free identifier in the
+// doctor report rather than a generic "Error".
+class ProjectionSchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectionSchemaError";
+  }
+}
+
+/**
+ * Columns `readProjectedMemoryBrowse` SELECTs from `memory_current` with no
+ * graceful fallback. `tags_json`/`preview_text` fall back via
+ * memoryCurrentSelectExpressions and `path_valid` falls back via the legacy
+ * full-scan branch — none of those make a browse query throw. A projection
+ * whose `memory_current` lacks any of these columns cannot serve browse
+ * queries: the SELECT throws and browse silently falls back to a full-corpus
+ * scan. Enumerated directly from readProjectedMemoryBrowse's SELECT list +
+ * ORDER BY references (issue #1848 round 3).
+ */
+const REQUIRED_MEMORY_CURRENT_COLUMNS = [
+  "memory_id",
+  "path_rel",
+  "category",
+  "status",
+  "created_at",
+  "updated_at",
+  "entity_ref",
+] as const;
+
+function assertProjectionSchemaReadable(db: BetterSqlite3Database): void {
+  const row = db
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_current'",
+    )
+    .get() as { name: string } | undefined;
+  if (!row?.name) {
+    throw new ProjectionSchemaError(
+      "projection schema is missing or was not initialized (memory_current table not found)",
+    );
+  }
+  // Round 3 (issue #1848): verify the columns readProjectedMemoryBrowse
+  // actually SELECT are present, not just that the table exists. A file like
+  // `CREATE TABLE memory_current (x INTEGER)` passed the round-2 table-existence
+  // + SELECT-1 check but cannot serve browse queries, so browse silently fell
+  // back to full-corpus scans while `remnic doctor` reported healthy. Classify
+  // such a stale/half-built table as present-but-invalid so the operator gets a
+  // rebuild hint instead of a false-clean bill of health.
+  const columns = listTableColumns(db, "memory_current");
+  const missing = REQUIRED_MEMORY_CURRENT_COLUMNS.filter((c) => !columns.has(c));
+  if (missing.length > 0) {
+    throw new ProjectionSchemaError(
+      `projection memory_current table is missing required column(s): ${missing.join(", ")}`,
+    );
+  }
+  // Also confirm the table is queryable — catches physical corruption that
+  // only surfaces on first read (the file opens but statements fail).
+  db.prepare("SELECT 1 FROM memory_current LIMIT 1").get();
+}
+
+/**
+ * Stat + attempt-open + schema-validate the memory projection WITHOUT keeping
+ * a handle, for the `remnic doctor` health check (issue #1829 / #1848).
+ * Distinguishes four states so operators can tell "not built yet" (normal) from
+ * "exists but broken" (needs a rebuild / native-binding rebuild). Never throws.
+ */
+export function probeProjectionHealth(memoryDir: string): ProjectionHealthProbe {
+  const dbPath = getMemoryProjectionPath(memoryDir);
+  if (!fs.existsSync(dbPath)) {
+    return { state: "absent", detail: "", nativeBindingMismatch: false };
+  }
+  let db: BetterSqlite3Database | null = null;
+  try {
+    db = projectionReadonlyOpener(dbPath, { readonly: true, fileMustExist: true });
+    // Validate the projection is actually USABLE, not just that the file
+    // opens (issue #1848 round 2): a file that opens but has the schema
+    // missing/corrupt previously reported ok, so doctor said healthy while
+    // browse silently fell back to full-corpus scans.
+    assertProjectionSchemaReadable(db);
+    return { state: "openable", detail: "", nativeBindingMismatch: false };
+  } catch (error) {
+    // If the file OPENED (db assigned) but the schema query failed, the
+    // native binding is fine — the projection itself is stale/corrupt.
+    if (db) {
+      return {
+        state: "present-but-invalid",
+        detail: displayErrorDetail(error),
+        nativeBindingMismatch: false,
+      };
+    }
+    return {
+      state: "unopenable",
+      detail: displayErrorDetail(error),
+      nativeBindingMismatch: isLikelyBetterSqlite3NativeBindingError(error),
+    };
+  } finally {
+    db?.close();
+  }
+}
 function updateProjectionBestEffort(
   memoryDir: string,
   sql: string,

package/src/operator-toolkit.ts

@@ -11,6 +11,7 @@ import {
   resolveOpenClawWorkspaceStatePath,
 } from "./native-knowledge.js";
 import { StorageManager } from "./storage.js";
+import { probeProjectionHealth } from "./memory-projection-store.js";
 import { listNamespaces } from "./namespaces/migrate.js";
 import { summarizeNamespaceMaintenanceHealth } from "./maintenance/namespace-maintenance-fanout.js";
 import {
@@ -1094,6 +1095,64 @@ export function summarizeProvenanceCoverage(
   return { counts, total: memories.length };
 }
 
+/**
+ * Memory projection health (issue #1829). A present-but-unopenable projection
+ * (wrong ABI / corrupt / bad perms) previously collapsed into the same silent
+ * null as a missing file, hiding native-binding mismatches behind full-corpus
+ * scans. This check stats + attempt-opens the projection so `remnic doctor`
+ * distinguishes "not built yet" (normal) from "exists but broken" (needs a
+ * rebuild / native-binding rebuild). Never throws.
+ */
+export function summarizeProjectionHealth(
+  config: Pick<PluginConfig, "memoryDir">,
+): OperatorDoctorCheck {
+  const probe = probeProjectionHealth(config.memoryDir);
+  if (probe.state === "absent") {
+    return {
+      key: "memory_projection",
+      status: "ok",
+      summary: "Memory projection index not built yet (normal until first maintenance run).",
+      details: { state: probe.state },
+    };
+  }
+  if (probe.state === "openable") {
+    return {
+      key: "memory_projection",
+      status: "ok",
+      summary: "Memory projection index opens cleanly.",
+      details: { state: probe.state },
+    };
+  }
+  if (probe.state === "present-but-invalid") {
+    const schemaDetailSuffix = probe.detail ? ` (${probe.detail})` : "";
+    return {
+      key: "memory_projection",
+      status: "error",
+      summary: `Memory projection index exists but its schema is missing or unreadable${schemaDetailSuffix}; memory browse is falling back to full-corpus scans.`,
+      remediation:
+        "Rebuild the projection with `remnic rebuild-memory-projection --write`.",
+      details: { state: probe.state, detail: probe.detail },
+    };
+  }
+  const nativeSuffix = probe.nativeBindingMismatch
+    ? " Native binding appears built for the wrong Node.js ABI."
+    : "";
+  const detailSuffix = probe.detail ? ` (${probe.detail})` : "";
+  return {
+    key: "memory_projection",
+    status: "error",
+    summary: `Memory projection index exists but could not be opened${detailSuffix}.${nativeSuffix}`,
+    remediation: probe.nativeBindingMismatch
+      ? "Rebuild the better-sqlite3 native binding for this Node.js (`node scripts/ensure-better-sqlite3.mjs` or `pnpm rebuild better-sqlite3`), then restart."
+      : "Rebuild the projection with `remnic rebuild-memory-projection --write`; check file permissions and integrity.",
+    details: {
+      state: probe.state,
+      detail: probe.detail,
+      nativeBindingMismatch: probe.nativeBindingMismatch,
+    },
+  };
+}
+
 export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise<OperatorDoctorReport> {
   const now = options.now ?? new Date();
   const configStatus = await loadCliPluginConfig(options.configPath);
@@ -1211,6 +1270,11 @@ export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise
     details: meta,
   });
 
+  // Memory projection health (issue #1829). Surfaces a present-but-unopenable
+  // projection (wrong ABI / corrupt) that previously degraded every memory
+  // list to a silent full-corpus scan. Absent and openable are both "ok".
+  checks.push(summarizeProjectionHealth(config));
+
   // Provenance coverage (issue #1575 PR 3). Operators need to see the
   // verified/unverified/none distribution grow as extraction backfills.
   // Best-effort: a read failure surfaces as a warn, not an error.

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]}`;
+}