A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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);