Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

fix: the first search waits out qmd's model download, and health round-trips a query (#239)

Brenno Ferraribd452174092a
diff --git a/.claude/scripts/lib/mcp-qmd-client.ts b/.claude/scripts/lib/mcp-qmd-client.ts
index f7f1db5..35cca76 100644
--- a/.claude/scripts/lib/mcp-qmd-client.ts
+++ b/.claude/scripts/lib/mcp-qmd-client.ts
@@ -167,8 +167,54 @@ export function scopeResults(
// The client — impure
// ---------------------------------------------------------------------------
+/** The budget for a call to a qmd that has already answered once. */
const CALL_TIMEOUT_MS = 45_000;
+/**
+ * The budget for the FIRST `tools/call` a child serves.
+ *
+ * qmd fetches its embedding and reranker models on first use — hundreds of MB
+ * over the network — and does it lazily, inside the first query rather than at
+ * startup. `initialize` returns in ~160ms regardless, so no readiness signal
+ * this client can await says anything about it.
+ *
+ * On 2026-08-22, on a machine qmd had never run a query on, the reranker
+ * (639MB) took ~70s to arrive. The flat 45s budget expired at 45.02s and the
+ * caller was told the vault could not answer. The download is bounded by the
+ * connection, not by us, so the only honest budget for that one call is a
+ * generous one — a wait is recoverable, and the wrong conclusion it replaced
+ * ("nothing is recorded") is not.
+ *
+ * Long is safe here for a reason that is easy to miss: a launcher that dies is
+ * caught by `failAll` on the child's `error`/`exit`, not by this timer. Nothing
+ * waits out this budget except a child that is alive and working.
+ */
+const COLD_CALL_TIMEOUT_MS = 10 * 60_000;
+
+/** Which budget a call gets. Exported because the boundary is worth locking. */
+export function callBudget(method: string, warmed: boolean): number {
+ return method === "tools/call" && !warmed ? COLD_CALL_TIMEOUT_MS : CALL_TIMEOUT_MS;
+}
+
+/**
+ * What a caller is told when a call runs out of budget.
+ *
+ * The cold case says what it is, because the previous message did not. The
+ * documented response to a failed search is to call `health` and, if that is
+ * clean, conclude the record is not there — so a bare `qmd timeout on
+ * tools/call` does not merely under-inform, it actively argues for the wrong
+ * conclusion. On 2026-08-22 the record existed and was complete.
+ */
+export function timeoutMessage(method: string, budgetMs: number, warmed: boolean): string {
+ const secs = Math.round(budgetMs / 1000);
+ if (method !== "tools/call" || warmed) return `qmd timeout on ${method} after ${secs}s`;
+ return (
+ `qmd timeout on ${method} after ${secs}s, on the first search this qmd process served. ` +
+ "qmd downloads its embedding and reranker models on first use (hundreds of MB); that is the likely cause. " +
+ "This says NOTHING about whether the vault holds the record — do not conclude it is missing. Retry."
+ );
+}
+
interface Pending {
resolve: (v: unknown) => void;
reject: (e: Error) => void;
@@ -176,7 +222,7 @@ interface Pending {
}
export interface QmdClient {
- call(method: string, params?: unknown): Promise<unknown>;
+ call(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
readonly ready: Promise<void>;
dispose(): void;
/**
@@ -185,6 +231,11 @@ export interface QmdClient {
* disable search for the whole life of the server.
*/
readonly alive: boolean;
+ /**
+ * True once a `tools/call` has returned from this child, i.e. qmd's models
+ * are loaded and the next call is on the fast path.
+ */
+ readonly warmed: boolean;
}
/**
@@ -204,6 +255,9 @@ export function createQmdClient(vaultRoot: string, launcherPath: string | null):
const pending = new Map<number, Pending>();
let alive = true;
+ // Whether any `tools/call` has come BACK from this child. False means the
+ // next one may still be paying qmd's one-time model download.
+ let warmed = false;
let rpcId = 0;
let buf = "";
@@ -243,24 +297,36 @@ export function createQmdClient(vaultRoot: string, launcherPath: string | null):
child.on("error", (e) => failAll(`qmd launcher failed: ${e.message}`));
child.on("exit", () => failAll("qmd launcher exited"));
- const call = (method: string, params?: unknown): Promise<unknown> =>
+ const call = (method: string, params?: unknown, timeoutMs?: number): Promise<unknown> =>
new Promise((resolve, reject) => {
// A call made AFTER the child died would otherwise sit in `pending`
// forever: failAll has already run, so nothing will ever reject it, and
// the timeout timer is unref'd. Callers that skip `await ready` — the
- // semantic-ordering path does — would block until the 45s timeout.
+ // semantic-ordering path does — would block until the timeout.
if (!alive) {
reject(new Error(`qmd unavailable (${method})`));
return;
}
const id = ++rpcId;
+ const budget = timeoutMs ?? callBudget(method, warmed);
const timer = setTimeout(() => {
- if (pending.delete(id)) reject(new Error(`qmd timeout on ${method}`));
- }, CALL_TIMEOUT_MS);
+ if (pending.delete(id)) reject(new Error(timeoutMessage(method, budget, warmed)));
+ }, budget);
// Node keeps the process alive for a pending timer; this one must not
// hold the server open on its own.
timer.unref?.();
- pending.set(id, { resolve, reject, timer });
+ pending.set(id, {
+ // Warmth is recorded on the RESULT, not on the send: a `tools/call`
+ // that is still in flight has not proved the models are loaded, and
+ // marking it early would hand the short budget to a concurrent second
+ // search that is queued behind the same download.
+ resolve: (v) => {
+ if (method === "tools/call") warmed = true;
+ resolve(v);
+ },
+ reject,
+ timer,
+ });
child.stdin?.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
});
@@ -285,6 +351,9 @@ export function createQmdClient(vaultRoot: string, launcherPath: string | null):
get alive() {
return alive;
},
+ get warmed() {
+ return warmed;
+ },
dispose: () => {
failAll("qmd client disposed");
child.kill();
@@ -328,3 +397,110 @@ export async function qmdSearch(
return { text: `search failed: ${message}`, withheld: 0, total: 0 };
}
}
+
+// ---------------------------------------------------------------------------
+// The probe — what `health` uses to prove search ANSWERS
+// ---------------------------------------------------------------------------
+
+/**
+ * How long `health` waits for search to answer before calling it degraded.
+ *
+ * Two budgets, because the probe inherits whatever the client is carrying. A
+ * warm client answers in ~31ms, so 5s is enormous headroom and `health` stays
+ * instant. A cold one pays qmd's model load first, and that is not a small
+ * number: measured at 2.9s with the models hot in the page cache and 10.5s with
+ * them cold, against ~970MB of GGUF across two models.
+ *
+ * A single 20s budget was the first attempt and it was wrong — 10.5s of a 20s
+ * budget is not headroom, and the failure mode it buys is the worst kind: a
+ * DEGRADED verdict on a healthy vault, from the one tool a caller consults
+ * precisely because they already suspect something is broken. Slow-and-correct
+ * beats fast-and-wrong here every time; `health` is rare and diagnostic.
+ */
+const PROBE_TIMEOUT_WARM_MS = 5_000;
+const PROBE_TIMEOUT_COLD_MS = 60_000;
+
+/**
+ * The probe's budget. Exported so the warm/cold split is pinned by a test
+ * rather than by a comment.
+ *
+ * Still far below `COLD_CALL_TIMEOUT_MS`: a real search should wait out a model
+ * download, a diagnostic should give up and REPORT. Timing out here is an
+ * answer, not a failure.
+ */
+export function probeBudget(warmed: boolean): number {
+ return warmed ? PROBE_TIMEOUT_WARM_MS : PROBE_TIMEOUT_COLD_MS;
+}
+
+export interface QmdProbe {
+ readonly ok: boolean;
+ readonly ms: number;
+ /** One clause, written to be appended to "search ...". */
+ readonly detail: string;
+}
+
+/**
+ * Round-trip a real search and report whether it answered.
+ *
+ * `health` used to report `launcher found`, which is a check on a FILE EXISTING.
+ * On 2026-08-22 that line read healthy while every search was timing out, on the
+ * one tool whose entire purpose is telling apart the failure modes behind an
+ * identical "no results" — so the instrument proved something other than what it
+ * said. Nothing short of a round-trip closes that gap.
+ *
+ * The probe goes through `subQueries` and omits `rerank`, exactly as `qmdSearch`
+ * does, so it pays the same model costs a real search pays. A cheaper probe —
+ * lexical only, or `rerank: false` — would have passed happily on 2026-08-22
+ * while the reranker download was still the thing blocking search, which is the
+ * same defect in a new place.
+ *
+ * Its own SHORT budget, not the client's: `health` is what a caller runs when
+ * something is already wrong, and a diagnostic that hangs for the cold-start
+ * budget is not a diagnostic. Timing out here is a REPORT, not a failure — it
+ * says search is not answering yet and names why that happens.
+ */
+export async function qmdProbe(client: QmdClient, timeoutMsOverride?: number): Promise<QmdProbe> {
+ // Read BEFORE the await: `client.warmed` flips as soon as any call returns,
+ // and a budget chosen after that would describe a state the probe did not
+ // start in.
+ const timeoutMs = timeoutMsOverride ?? probeBudget(client.warmed);
+ const started = Date.now();
+ try {
+ await client.ready;
+ const out = (await client.call(
+ "tools/call",
+ {
+ name: "query",
+ arguments: { searches: subQueries("vault"), intent: "health probe", limit: 1, minScore: 0.4 },
+ },
+ timeoutMs,
+ )) as { structuredContent?: { results?: unknown } } | null;
+ const ms = Date.now() - started;
+ // Answering with no structured results is its own failure: `scopeResults`
+ // cannot scope-check hits it cannot see, so search would return
+ // "(search unavailable)" for every query while the transport looks fine.
+ if (!Array.isArray(out?.structuredContent?.results)) {
+ return { ok: false, ms, detail: `answered in ${ms}ms but returned no structured results — hits cannot be scope-checked` };
+ }
+ return { ok: true, ms, detail: `answered in ${ms}ms` };
+ } catch (e) {
+ const ms = Date.now() - started;
+ const message = e instanceof Error ? e.message : String(e);
+ // A probe timeout does not make the same claim a search timeout makes.
+ // The probe's budget is short so `health` stays fast; search's is minutes.
+ // Echoing the raw message here would publish "timeout after 20s" as if 20s
+ // were what search allows, and someone would tune the wrong number.
+ if (message.startsWith("qmd timeout")) {
+ return {
+ ok: false,
+ ms,
+ detail:
+ `did not answer within ${Math.round(timeoutMs / 1000)}s — search is DEGRADED right now. ` +
+ "qmd downloads its embedding and reranker models on first use (hundreds of MB); " +
+ "on a vault new to this machine that is the likely cause, and it clears itself once the download lands. " +
+ "A real search waits far longer than this probe does.",
+ };
+ }
+ return { ok: false, ms, detail: `DID NOT ANSWER (${message})` };
+ }
+}
diff --git a/.claude/scripts/lib/mcp-server.ts b/.claude/scripts/lib/mcp-server.ts
index 88101d4..49f2f6c 100644
--- a/.claude/scripts/lib/mcp-server.ts
+++ b/.claude/scripts/lib/mcp-server.ts
@@ -27,7 +27,7 @@ import {
vaultRelKeyRaw,
} from "./mcp-exposure.ts";
import { expandNote } from "./mcp-graph.ts";
-import { qmdSearch, type QmdClient } from "./mcp-qmd-client.ts";
+import { qmdProbe, qmdSearch, type QmdClient } from "./mcp-qmd-client.ts";
import { callerProject, callerProjectSource, isVaultItself, PROJECT_MARKER, sumAuditField, sanitize } from "./mcp-caller.ts";
import { callerPlatforms, digestsFrom, resolvableNames } from "./mcp-memory-bridge.ts";
import { captureNote, describeToolMarkup, toolMarkupRefusal } from "./mcp-capture.ts";
@@ -703,8 +703,13 @@ export function createHandlers(deps: ServerDeps): Handlers {
].join("\n");
}
- function callHealth(): string {
+ async function callHealth(): Promise<string> {
const who = caller();
+ // Run BEFORE anything is rendered, because the line it feeds used to be a
+ // check on the launcher FILE existing. On 2026-08-22 that line read healthy
+ // while every search was timing out — on the one tool whose job is telling
+ // apart the failure modes behind an identical "no results".
+ const probe = await qmdProbe(qmd());
// Populate the cache before reporting on it. `recall` tells the user to run
// health when a memory is missing, so this is routinely the FIRST call a
// server serves — and "3 memories / 0 entries held" reads as a parse
@@ -747,7 +752,7 @@ export function createHandlers(deps: ServerDeps): Handlers {
// server could not re-read, served from an older parse.
`Parsed store: ${parsed} entr${parsed === 1 ? "y" : "ies"}${memoryIndex.stats.stale ? ` (${memoryIndex.stats.stale} served from an older parse — check permissions)` : ""}`,
`Exposed roots: ${policy.roots.join(", ") || "(none)"} [${policy.source}]`,
- `Search index: ${ctx.qmdIndex ?? "(qmd default)"} · launcher ${ctx.qmdLauncher ? "found" : "NOT FOUND"}`,
+ `Search index: ${ctx.qmdIndex ?? "(qmd default)"} · launcher ${ctx.qmdLauncher ? "found" : "NOT FOUND"} · search ${probe.detail}`,
// `reason` is the one tool that spawns a session, and nothing bounds it.
// Reporting the day's usage is what stands in for a limit: the answer to
// "where did that go" has to exist somewhere, and this is where.
@@ -783,7 +788,12 @@ export function createHandlers(deps: ServerDeps): Handlers {
(p) => `promotion marker in ${p} could not be parsed — it is invisible to every consumer.`,
),
];
- const all = [...h.warnings, ...mine];
+ // The probe failing is the loudest thing this tool can report: it means
+ // search is not answering NOW, which every other line here would let a
+ // caller mistake for an empty vault. It goes in the warnings block
+ // because "No warnings." printing during a live search outage is the
+ // exact failure this probe exists to end.
+ const all = [...h.warnings, ...mine, ...(probe.ok ? [] : [`search ${probe.detail}`])];
return all.length ? `Warnings:\n${all.map((w) => `- ${w}`).join("\n")}` : "No warnings.";
})(),
...(h.notes.length ? ["", `Notes:\n${h.notes.map((n) => `- ${n}`).join("\n")}`] : []),
@@ -830,7 +840,7 @@ export function createHandlers(deps: ServerDeps): Handlers {
case "reason":
return session.ok(id, text(await callReason(args)));
case "health":
- return session.ok(id, text(callHealth()));
+ return session.ok(id, text(await callHealth()));
default:
return session.fail(id, `unknown tool ${p.name}`, -32602);
}
diff --git a/.claude/scripts/lib/mcp-tools.ts b/.claude/scripts/lib/mcp-tools.ts
index bc7b0e2..857bc48 100644
--- a/.claude/scripts/lib/mcp-tools.ts
+++ b/.claude/scripts/lib/mcp-tools.ts
@@ -266,7 +266,7 @@ export const TOOLS: readonly ToolDef[] = [
{
name: "health",
description:
- "Check that this vault's wiring is intact: where memories actually live, which roots are exposed, whether the search index is reachable, and whether any memories reference a project that no longer resolves. Call this when something that should be in the vault cannot be found — every failure in this layer presents identically as 'no results', and this is what tells them apart.",
+ "Check that this vault's wiring is intact: where memories actually live, which roots are exposed, whether search ANSWERS (a real query is run and its latency reported, not merely a launcher located), and whether any memories reference a project that no longer resolves. Call this when something that should be in the vault cannot be found — every failure in this layer presents identically as 'no results', and this is what tells them apart. A search reported as DEGRADED here means a failed search proved nothing about what the vault holds; retry it before concluding anything is missing.",
inputSchema: { type: "object", properties: {} },
annotations: { title: "Check vault wiring", ...READ_ONLY },
},
diff --git a/.claude/scripts/tests/mcp-memory-bridge.test.ts b/.claude/scripts/tests/mcp-memory-bridge.test.ts
index 5be4168..7031d12 100644
--- a/.claude/scripts/tests/mcp-memory-bridge.test.ts
+++ b/.claude/scripts/tests/mcp-memory-bridge.test.ts
@@ -49,6 +49,8 @@ function fakeQmd(files: string[] | null, fail = false): QmdClient {
ready: Promise.resolve(),
dispose: () => {},
alive: true,
+ // This fake never pays a model load, so it is warm by construction.
+ warmed: true,
call: async () => {
if (fail) throw new Error("index down");
return files === null ? {} : { structuredContent: { results: files.map((f) => ({ file: f })) } };
diff --git a/.claude/scripts/tests/mcp-qmd-client.test.ts b/.claude/scripts/tests/mcp-qmd-client.test.ts
index 7b55f98..53918ff 100644
--- a/.claude/scripts/tests/mcp-qmd-client.test.ts
+++ b/.claude/scripts/tests/mcp-qmd-client.test.ts
@@ -12,6 +12,8 @@
import { test, describe } from "node:test";
import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
import { join } from "node:path";
import {
@@ -21,9 +23,83 @@ import {
scopeResults,
subQueries,
createQmdClient,
+ callBudget,
+ timeoutMessage,
+ qmdProbe,
+ probeBudget,
type QmdHit,
+ type QmdClient,
} from "../lib/mcp-qmd-client.ts";
+/**
+ * Write a stand-in qmd launcher that speaks just enough MCP to exercise the
+ * client, and return its path.
+ *
+ * A fake rather than the real qmd because the behaviours under test are all
+ * about TIMING and SHAPE — a call that never answers, a reply with no
+ * structured results — and none of them can be provoked on demand from a
+ * working qmd. The one that matters most, a first call that outlives its
+ * budget, is reproducible here in 300ms and was reproducible in production
+ * only on a machine that had never run qmd before.
+ *
+ * Modes: `ok` answers with structured results, `nostruct` answers without
+ * them, `silent` completes the handshake and then never answers a tools/call.
+ * Every mode answers `initialize`, because the handshake was never the thing
+ * that broke.
+ */
+function fakeLauncher(dir: string, mode: "ok" | "nostruct" | "silent"): string {
+ const file = join(dir, "fake-qmd.mjs");
+ writeFileSync(
+ file,
+ `import { createInterface } from "node:readline";
+const MODE = ${JSON.stringify(mode)};
+const send = (m) => process.stdout.write(JSON.stringify(m) + "\\n");
+createInterface({ input: process.stdin }).on("line", (line) => {
+ let msg;
+ try { msg = JSON.parse(line); } catch { return; }
+ if (typeof msg.id !== "number") return;
+ if (msg.method === "initialize") {
+ send({ jsonrpc: "2.0", id: msg.id, result: { protocolVersion: "2025-11-25", capabilities: {} } });
+ return;
+ }
+ if (msg.method !== "tools/call") return;
+ if (MODE === "silent") return;
+ if (MODE === "nostruct") {
+ send({ jsonrpc: "2.0", id: msg.id, result: { content: [{ type: "text", text: "no structure here" }] } });
+ return;
+ }
+ send({ jsonrpc: "2.0", id: msg.id, result: { structuredContent: { results: [{ file: "v/brain/Gotchas.md", score: 0.9, title: "t", snippet: "s" }] } } });
+});
+`,
+ "utf-8",
+ );
+ return file;
+}
+
+/**
+ * Run `fn` against a fake-backed client and ALWAYS reap the child.
+ *
+ * The cleanup lives in `finally` rather than after the assertions because a
+ * failing assertion would otherwise skip `dispose`, and the orphaned child
+ * holds its stdin open — which stops the test runner draining its event loop.
+ * The first draft of these tests did exactly that: one broken assertion turned
+ * a clean failure into a hang, i.e. into the slowest possible way to learn the
+ * same thing.
+ */
+async function withFake<T>(
+ mode: "ok" | "nostruct" | "silent",
+ fn: (c: QmdClient) => Promise<T>,
+): Promise<T> {
+ const dir = mkdtempSync(join(tmpdir(), "qmd-fake-"));
+ const c = createQmdClient(process.cwd(), fakeLauncher(dir, mode));
+ try {
+ return await fn(c);
+ } finally {
+ c.dispose();
+ rmSync(dir, { recursive: true, force: true });
+ }
+}
+
const VAULT = "C:/Dev/myvault";
/** The set a caller scoped to `brain/` and `projects/` would get. */
@@ -282,3 +358,175 @@ describe("rendering", () => {
assert.ok(!scopeResults([hit("myvault/brain/Gotchas.md")], ALLOWED).text.includes(".md:"));
});
});
+
+// ---------------------------------------------------------------------------
+// Cold start
+//
+// On 2026-08-22 a foreign repo's first search of a session failed with
+// `qmd timeout on tools/call`, `health` reported no warnings, and the identical
+// query succeeded minutes later. The cause was not the query and not a
+// readiness race — `qmdSearch` already awaits `ready`, and the handshake
+// measured 161ms. qmd was downloading its 639MB reranker model inside the first
+// query; the flat 45s budget expired at 45.02s.
+//
+// What makes that expensive is not the wait. The documented response to a
+// failed search is to call `health` and, if it is clean, conclude the record is
+// not there — so these tests are as much about what the caller is TOLD as about
+// what is waited for.
+// ---------------------------------------------------------------------------
+
+describe("call budgets", () => {
+ test("the first tools/call is given room for a model download", () => {
+ // 45s was not a wrong number so much as a wrong SHAPE: the cost it bounds
+ // is a network fetch of a few hundred MB, whose duration belongs to the
+ // connection. Anything that could plausibly be beaten by a slow link would
+ // reintroduce the same failure on a worse day.
+ assert.ok(
+ callBudget("tools/call", false) >= 5 * 60_000,
+ "a cold search must tolerate a slow download, not race it",
+ );
+ });
+
+ test("a warmed client goes back to the short budget", () => {
+ // The generous budget is a one-time concession. Keeping it would mean a
+ // genuinely wedged qmd hangs a caller for ten minutes with no signal.
+ assert.ok(callBudget("tools/call", true) < callBudget("tools/call", false));
+ assert.equal(callBudget("tools/call", true), 45_000);
+ });
+
+ test("the handshake is never given the cold budget", () => {
+ // `initialize` is a pure handshake — measured at ~160ms — and pays none of
+ // the model cost. Extending its budget would only delay the report of a
+ // launcher that is answering but broken.
+ assert.equal(callBudget("initialize", false), callBudget("tools/call", true));
+ });
+});
+
+describe("what a timeout tells the caller", () => {
+ test("a cold search timeout names the cause and blocks the wrong conclusion", () => {
+ const m = timeoutMessage("tools/call", 600_000, false);
+ assert.match(m, /download/i, "the cause has to be named or it reads as a broken vault");
+ assert.match(m, /first search/i);
+ // The load-bearing assertion. A caller who follows the documented failure
+ // path lands on "nothing is recorded"; on 2026-08-22 the record existed and
+ // was complete, and re-deriving it would have cost a night's work.
+ assert.match(m, /do not conclude it is missing/i);
+ assert.match(m, /retry/i);
+ });
+
+ test("a warmed timeout stays terse and claims nothing about downloads", () => {
+ // Blaming a download for every timeout would make the cold message noise,
+ // and noise is how a real signal stops being read.
+ const m = timeoutMessage("tools/call", 45_000, true);
+ assert.doesNotMatch(m, /download/i);
+ assert.match(m, /45s/);
+ });
+
+ test("the handshake timeout is terse too", () => {
+ assert.doesNotMatch(timeoutMessage("initialize", 45_000, false), /download/i);
+ });
+});
+
+describe("client warmth", () => {
+ test("a fresh client is not warm", () => {
+ const c = createQmdClient(process.cwd(), join(process.cwd(), "no-launcher.mjs"));
+ try {
+ assert.equal(c.warmed, false, "nothing has come back yet, so nothing is proven");
+ } finally {
+ c.dispose();
+ }
+ });
+
+ test("the handshake does not count as warmth", async () => {
+ // A handshake proves the process speaks MCP. It measured ~160ms in
+ // production while the thing that actually blocked search — a 639MB model
+ // download — had not started. Treating it as warmth is how 45s came to look
+ // like enough.
+ await withFake("ok", async (c) => {
+ await c.ready;
+ assert.equal(c.warmed, false);
+ });
+ });
+
+ test("a tools/call still IN FLIGHT does not confer warmth", async () => {
+ // The assertion the whole flag exists for. Warmth means "the models are
+ // loaded", and only a reply proves that. Setting it when the request is
+ // SENT would hand the short 45s budget to a second search queued behind the
+ // very download the first one is still waiting on — reproducing the
+ // original failure on the caller least able to explain it.
+ await withFake("silent", async (c) => {
+ await c.ready;
+ const inflight = c.call("tools/call", { name: "query", arguments: {} }, 400);
+ await new Promise((r) => setTimeout(r, 150));
+ assert.equal(c.warmed, false, "sent is not answered");
+ await assert.rejects(() => inflight);
+ assert.equal(c.warmed, false, "a timed-out call proves nothing either");
+ });
+ });
+
+ test("a tools/call that returns confers warmth", async () => {
+ await withFake("ok", async (c) => {
+ await c.call("tools/call", { name: "query", arguments: {} });
+ assert.equal(c.warmed, true);
+ });
+ });
+});
+
+describe("the health probe", () => {
+ test("a cold probe waits for the model load; a warm one does not", () => {
+ // Measured: ~31ms warm, 2.9s with the models hot in the page cache, 10.5s
+ // with them cold. A single budget sized for the warm case would report a
+ // healthy vault as DEGRADED — from the one tool a caller reaches for when
+ // they already suspect a problem, which is the worst place to be wrong.
+ assert.ok(probeBudget(false) >= 30_000, "a cold probe must outlast a ~10s model load");
+ assert.ok(probeBudget(true) <= 10_000, "a warm probe must keep health snappy");
+ assert.ok(probeBudget(false) > probeBudget(true));
+ // A real search waits out a download; a diagnostic gives up and REPORTS.
+ assert.ok(probeBudget(false) < callBudget("tools/call", false));
+ });
+
+ test("a qmd that answers is reported ok, with a latency", async () => {
+ await withFake("ok", async (c) => {
+ const r = await qmdProbe(c, 5_000);
+ assert.equal(r.ok, true);
+ assert.match(r.detail, /answered in \d+ms/);
+ });
+ });
+
+ test("answering without structured results is NOT healthy", async () => {
+ // `scopeResults` cannot scope-check hits it cannot see, so every search
+ // would return "(search unavailable)" while the transport looked perfect.
+ // A probe that only checked for a reply would call this fine — and a probe
+ // that reports fine during an outage is the defect this whole change is
+ // about, just relocated.
+ await withFake("nostruct", async (c) => {
+ const r = await qmdProbe(c, 5_000);
+ assert.equal(r.ok, false);
+ assert.match(r.detail, /structured/i);
+ });
+ });
+
+ test("a qmd that never answers is reported degraded", async () => {
+ await withFake("silent", async (c) => {
+ const r = await qmdProbe(c, 300);
+ assert.equal(r.ok, false);
+ assert.match(r.detail, /DEGRADED/);
+ assert.match(r.detail, /download/i, "the likeliest cause has to travel with the report");
+ // The probe's budget is short so `health` stays fast; search's is minutes.
+ // Echoing the raw timeout would publish the probe's number as if it were
+ // search's, and the next person to tune a timeout would tune the wrong one.
+ assert.doesNotMatch(r.detail, /qmd timeout/);
+ });
+ });
+
+ test("a launcher that will not start is reported as not answering", async () => {
+ const c = createQmdClient(process.cwd(), join(process.cwd(), "absent-launcher.mjs"));
+ try {
+ const r = await qmdProbe(c, 2_000);
+ assert.equal(r.ok, false);
+ assert.match(r.detail, /DID NOT ANSWER/);
+ } finally {
+ c.dispose();
+ }
+ });
+});
diff --git a/.claude/scripts/tests/om-mcp.integration.test.ts b/.claude/scripts/tests/om-mcp.integration.test.ts
index 748f634..f7758f4 100644
--- a/.claude/scripts/tests/om-mcp.integration.test.ts
+++ b/.claude/scripts/tests/om-mcp.integration.test.ts
@@ -274,6 +274,29 @@ describe("the om server on the wire", () => {
assert.match(t, /model: your CLI default/);
});
+ test("health reports a search outage instead of reporting no warnings", async () => {
+ // The whole point of the tool, and the thing it failed at on 2026-08-22: a
+ // foreign repo's search was timing out, `health` said `launcher found` and
+ // `No warnings.`, and the caller had every reason to conclude the vault
+ // simply held no record. It held a complete one.
+ //
+ // This fixture vault carries no qmd launcher, so search is genuinely dead
+ // here — which makes it the outage, not a mock of one. `launcher found` is
+ // a check on a FILE EXISTING and can never notice this; only a round trip
+ // can.
+ const t = textOf(await call("tools/call", { name: "health", arguments: {} }));
+ assert.doesNotMatch(t, /No warnings\./, "a live search outage must not render as a clean bill of health");
+
+ // Asserted against the WARNINGS BLOCK, not the whole report. The first
+ // version of this test searched the full text and passed with the warning
+ // removed, because `search DID NOT ANSWER` also appears on the `Search
+ // index:` line — so it proved the probe ran, never that its verdict was
+ // raised where a caller looks. That is the same defect as `launcher found`,
+ // committed by the test written to catch it.
+ const block = (t.split(/^Warnings:\n/m)[1] ?? "").split(/\n\nNotes:/)[0] ?? "";
+ assert.match(block, /^- search DID NOT ANSWER/m, "the outage has to be raised as a warning, not merely reported inline");
+ });
+
test("recall on an empty store explains itself rather than returning nothing", async () => {
const r = await call("tools/call", { name: "recall", arguments: { explain: true } });
const t = textOf(r);